Custom Component Overrides

Custom Component Overrides let you replace individual UI components inside enosix Cloud UI with your own implementations — without modifying the core library. Use this approach when you need to change the appearance or behavior of a specific component (for example, a navigation bar, a price display, or the embedded viewer) while leaving the rest of the application intact.

How It Works

enosix Cloud UI is distributed as an npm package (@enosix/cloud-ui). Your template project depends on this package and uses Vite's resolve.alias to intercept specific import paths at build time. When Vite encounters an import for a Cloud UI component you have aliased, it loads your custom file instead.

The original component is still available for import if you want to wrap or extend it rather than replace it entirely.

Prerequisites

A Cloud UI template project created with create-cloud-ui (see Setup and Deployment)
Familiarity with React and TypeScript
Vite as your build tool (all Cloud UI templates use Vite by default)

Step-by-Step Guide

Step 1: Identify the component to override

Locate the import path of the component you want to replace. Import paths follow the pattern:

@enosix/cloud-ui/<path-to-component>

Examples:

@enosix/cloud-ui/pages/TestHarness/components/EmbeddedViewer
@enosix/cloud-ui/apps/vc-ui/components/NavBar
@enosix/cloud-ui/shared/components/Price

Step 2: Create your custom component

Create a new file in your project's src/custom/ directory (or any location you prefer). Your component must accept the same props as the original.

To find the expected props, import the type from the Cloud UI package:

// src/custom/MyCustomEmbeddedViewer.tsx
import { EmbeddedViewerProps } from '@enosix/cloud-ui/shared/types/props'
import EmbeddedViewer from '@enosix/cloud-ui/original/pages/TestHarness/components/EmbeddedViewer'
import { Typography } from '@mui/material'
import { useTranslation } from 'react-i18next'

const MyCustomEmbeddedViewer = (props: EmbeddedViewerProps) => {
    const { t } = useTranslation()

    return (
        <>
            <Typography variant="caption" color="primary" sx={{ paddingLeft: '20px' }}>
                {t('TestHarness.CustomBanner.Title')}
            </Typography>
            {/* Render the original component with all its props */}
            <EmbeddedViewer {...props} />
        </>
    )
}

export default MyCustomEmbeddedViewer

Tip: Import the original component from the @enosix/cloud-ui/original/... path to wrap it rather than replace it entirely. This lets you add content above, below, or around the default implementation.

Step 3: Configure the Vite alias

Open your template project's vite.config.ts and add two entries for each component you are overriding: one in optimizeDeps.exclude (to prevent caching issues during development) and one in resolve.alias (to redirect the import).

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react-swc'
import * as path from 'node:path'

export default defineConfig({
    plugins: [react()],
    optimizeDeps: {
        exclude: [
            // Prevent the original component from being cached during dev
            '@enosix/cloud-ui/pages/TestHarness/components/EmbeddedViewer',
        ],
    },
    resolve: {
        alias: {
            // Redirect the import to your custom implementation
            '@enosix/cloud-ui/pages/TestHarness/components/EmbeddedViewer': path.resolve(
                __dirname,
                'src/custom/MyCustomEmbeddedViewer.tsx',
            ),
        },
    },
})

Step 4: Verify the override

Start the development server and confirm your component renders in place of the original:

pnpm run dev

Open the application in your browser and navigate to the area where the overridden component appears. Your custom implementation should be visible.

Override Scope

Choose the right import path based on how broadly you want the override to apply:

Scope	Import path pattern	Effect
App-specific	`@enosix/cloud-ui/apps/vc-ui/components/...`	Affects only Variant Configuration UI
App-specific	`@enosix/cloud-ui/apps/salesdoc-ui/components/...`	Affects only Sales Document UI
Shared	`@enosix/cloud-ui/shared/components/...`	Affects all apps that use the component
Test Harness	`@enosix/cloud-ui/pages/TestHarness/components/...`	Affects the development test harness only

Avoid overriding components in @enosix/cloud-ui/core/ unless absolutely necessary, as these are infrastructure-level and changes can have unintended side effects.

Overriding Translations

In addition to component overrides, you can override or extend any user-facing text by providing a custom TranslationsSettings object to the providers in src/main.tsx.

// src/main.tsx
import { TranslationsSettings } from '@enosix/cloud-ui/shared/types/props'

const translations: TranslationsSettings = {
    fallbackLng: 'en',
    resources: {
        en: {
            ns1: {
                VcUi: {
                    Navbar: {
                        FinalizeButton: 'Complete Order',
                    },
                },
                SalesDocUi: {
                    CreateOrder: {
                        ButtonLabel: 'New Sales Order',
                    },
                },
            },
        },
    },
}

// Pass to both providers
<EmbeddedProviders translations={translations} />
<TestHarnessProviders translations={translations} appIds={['vc-ui']} />

Only include the keys you want to change. All other strings fall back to the Cloud UI defaults.

Custom Component Overrides

How It Works​

Prerequisites​

Step-by-Step Guide​

Step 1: Identify the component to override​

Step 2: Create your custom component​

Step 3: Configure the Vite alias​

Step 4: Verify the override​

Override Scope​

Overriding Translations​