***

title: 'Customizing Forms'
metaTitle: 'Customizing Forms in the Vendure Dashboard'
metaDescription: 'Choose the right API for replacing native detail-page inputs or rendering custom fields with your own Vendure Dashboard input components.'
------------------------------------------------------------------------------------------------------------------------------------------------------------

The Dashboard has two different APIs for customizing form inputs. Choose based on what kind of field you are changing:

| I want to...                                                                 | Use this API                                                              | How it is selected                                                                   |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Replace the rendered input for a native entity field, such as `Product.slug` | [`detailForms[].inputs`](#replacing-native-detail-page-fields)            | Target a specific `pageId`, `blockId`, and `field`                                   |
| Use my own input for a plugin-defined custom field                           | [`customFormComponents.customFields`](#custom-field-components)           | Register a component ID, then reference it from the custom field's `ui.component`    |
| Use my own input for a configurable operation argument                       | [`customFormComponents.customFields`](#configurable-operation-components) | Register a component ID, then reference it from the argument config's `ui.component` |

Both APIs use the same [DashboardFormComponent type](/current/core/reference/dashboard/extensions-api/form-components#dashboardformcomponent), but they are registered differently. Use `detailForms[].inputs` only when you are replacing a native field on a specific detail page. Use `customFormComponents.customFields` when the field itself is defined in your plugin configuration.

## Shared Component API

All form components must implement the [DashboardFormComponent type](/current/core/reference/dashboard/extensions-api/form-components#dashboardformcomponent).

This type is based on the props that are made available from `react-hook-form`, which is the
underlying form library used by the Dashboard.

### Component metadata

In addition to the standard React component signature, a dashboard form component can define a static `metadata` property.
This lets the dashboard know how your component should be rendered in certain contexts.

* **`isListInput`**: Declare whether your component is intended for list fields. Use `'dynamic'` if it can handle both list and non-list fields.
* **`isFullWidth`**: When `true`, the dashboard will render the field so it spans the full width of the standard 2-column detail form grids (e.g. `DetailFormGrid`).

```tsx
import { DashboardFormComponentProps } from '@vendure/dashboard';

export function MyCustomInput(props: DashboardFormComponentProps<string>) {
    return <textarea value={props.value} onChange={e => props.onChange(e.target.value)} />;
}

MyCustomInput.metadata = {
    isFullWidth: true,
};
```

Here's an example custom form component that has been annotated to explain the typical parts you will be working with:

```tsx title="src/plugins/my-plugin/dashboard/components/color-picker.tsx"
import {
    Button,
    Card,
    CardContent,
    cn,
    DashboardFormComponent,
    Input,
    useFormContext,
} from '@vendure/dashboard';
import { useState } from 'react';

// By typing your component as DashboardFormComponent, the props will be correctly typed
export const ColorPickerComponent: DashboardFormComponent = ({ value, onChange, name }) => {
    // You can use any of the built-in React hooks as usual
    const [isOpen, setIsOpen] = useState(false);

    // To access the react-hook-form context, use this hook.
    // This is useful for getting information about the current
    // field, or even other fields in the form, which allows you
    // to create advanced components that depend on the state of
    // other fields in the form.
    const { getFieldState } = useFormContext();
    // The current field name is always passed in as a prop, allowing
    // you to look up the field state
    const error = getFieldState(name).error;

    const colors = ['#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FECA57', '#FF9FF3', '#54A0FF', '#5F27CD'];

    return (
        <div className="space-y-2">
            <div className="flex items-center space-x-2">
                <Button
                    type="button"
                    variant="outline"
                    size="icon"
                    className={cn('w-8 h-8 border-2 border-gray-300 p-0', error && 'border-red-500')}
                    style={{ backgroundColor: error ? 'transparent' : value || '#ffffff' }}
                    onClick={() => setIsOpen(!isOpen)}
                />
                <Input value={value || ''} onChange={e => onChange(e.target.value)} placeholder="#ffffff" />
            </div>

            {isOpen && (
                <Card>
                    <CardContent className="grid grid-cols-4 gap-2 p-2">
                        {colors.map(color => (
                            <Button
                                key={color}
                                type="button"
                                variant="outline"
                                size="icon"
                                className="w-8 h-8 border-2 border-gray-300 hover:border-gray-500 p-0"
                                style={{ backgroundColor: color }}
                                onClick={() => {
                                    onChange(color);
                                    setIsOpen(false);
                                }}
                            />
                        ))}
                    </CardContent>
                </Card>
            )}
        </div>
    );
};
```

Here's how this component will look when rendered in your form:

![Color picker component](./color-picker.webp)

## Custom Field Components

Use this path for fields defined in your Vendure custom field configuration. Custom field components are registered globally with an ID, then selected from the custom field's `ui.component` property. They are not targeted by `pageId`, `blockId`, or field location.

Let's configure a [custom field](/current/core/developer-guide/custom-fields/) which uses the `ColorPickerComponent` as its form component.

First we need to register the component with the `defineDashboardExtension` function:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';
import { ColorPickerComponent } from './components/color-picker';

defineDashboardExtension({
    customFormComponents: {
        // Custom field components for custom fields
        customFields: [
            {
                // The "id" is a global identifier for this custom component. We will // [!code highlight]
                // reference it in the next step. // [!code highlight]
                id: 'color-picker', // [!code highlight]
                component: ColorPickerComponent, // [!code highlight]
            },
        ],
    },
    // ... other extension properties
});
```

Now that we've registered it as a custom field component, we can use it in our custom field definition.

```tsx title="src/plugins/my-plugin/my.plugin.ts"
@VendurePlugin({
    // ...
    configuration: config => {
        config.customFields.Product.push({
            name: 'color',
            type: 'string',
            pattern: '^#[A-Fa-f0-9]{6}$',
            label: [{ languageCode: LanguageCode.en, value: 'Color' }],
            description: [{ languageCode: LanguageCode.en, value: 'Main color for this product' }],
            ui: {
                // This is the ID of the custom field // [!code highlight]
                // component we registered above. // [!code highlight]
                component: 'color-picker', // [!code highlight]
            },
        });
        return config;
    },
})
export class MyPlugin {}
```

## Configurable Operation Components

The `ColorPickerComponent` can also be used as a [configurable operation argument](/current/core/developer-guide/strategies-configurable-operations/#configurable-operations) component. For example, we can add a color code
to a shipping calculator:

```tsx title="src/plugins/my-plugin/config/custom-shipping-calculator.ts"
const customShippingCalculator = new ShippingCalculator({
    code: 'custom-shipping-calculator',
    description: [{ languageCode: LanguageCode.en, value: 'Custom Shipping Calculator' }],
    args: {
        color: {
            type: 'string',
            label: [{ languageCode: LanguageCode.en, value: 'Color' }],
            description: [
                { languageCode: LanguageCode.en, value: 'Color code for this shipping calculator' },
            ],
            ui: { component: 'color-picker' }, // [!code highlight]
        },
    },
    calculate: (ctx, order, args) => {
        // ...
    },
});
```

## Replacing Native Detail-Page Fields

Use this path when you want to replace the rendered input for a native field on an existing detail page, such as `Product.description`, `Product.slug`, or `Customer.emailAddress`. These overrides are targeted to a specific page, block, and field.

For plugin-defined custom fields, use [custom field components](#custom-field-components) instead.

Let's say we want to use a plain text editor for the product description field rather than the default
html-based editor.

```tsx title="src/plugins/my-plugin/dashboard/components/markdown-editor.tsx"
import { DashboardFormComponent, Textarea } from '@vendure/dashboard';

// This is a simplified example - a real markdown editor should use
// a library that handles markdown rendering and editing.
export const MarkdownEditorComponent: DashboardFormComponent = props => {
    return (
        <Textarea
            className="font-mono"
            ref={props.ref}
            onBlur={props.onBlur}
            value={props.value}
            onChange={e => props.onChange(e.target.value)}
            disabled={props.disabled}
        />
    );
};
```

You can then use this component in your detail form definition:

```tsx title="src/plugins/my-plugin/dashboard/index.tsx"
import { defineDashboardExtension } from '@vendure/dashboard';
import { MarkdownEditorComponent } from './components/markdown-editor';

defineDashboardExtension({
    detailForms: [
        {
            pageId: 'product-detail', // [!code highlight]
            inputs: [
                // [!code highlight]
                {
                    // [!code highlight]
                    blockId: 'main-form', // [!code highlight]
                    field: 'description', // [!code highlight]
                    component: MarkdownEditorComponent, // [!code highlight]
                }, // [!code highlight]
            ], // [!code highlight]
        },
    ],
});
```

### Targeting Input Components

Native detail-page input overrides are targeted in two levels:

* **`pageId`**: The ID of the page, defined on the surrounding `detailForms[]` entry.
* **`blockId`**: The ID of the form block, defined on each `inputs[]` item.
* **`field`**: The native field name to replace, defined on each `inputs[]` item.

```tsx
defineDashboardExtension({
    detailForms: [
        {
            pageId: 'customer-detail',
            inputs: [
                {
                    blockId: 'main-form',
                    field: 'emailAddress',
                    component: EmailInputComponent,
                },
            ],
        },
    ],
});
```

You can discover the required IDs by turning on dev mode:

![Dev mode](./dev-mode.webp)

and then hovering over any of the form elements will allow you to view the IDs:

![Form element IDs](./locator.webp)

## Form Validation

Form validation is handled by the `react-hook-form` library, which is used by the Dashboard. Internally,
the Dashboard uses the `zod` library to validate the form data, based on the configuration of the custom field or
operation argument.

You can access validation data for the current field or the whole form by using the `useFormContext` hook.

:::note\[Error Messages]
Your component does not need to handle standard error messages - the Dashboard will handle them for you.

For example, if your custom field specifies a `pattern` property, the Dashboard will automatically display an error message
if the input does not match the pattern.
:::

```tsx title="src/plugins/my-plugin/dashboard/components/validated-input.tsx"
import { DashboardFormComponent, Input, Alert, AlertDescription, useFormContext } from '@vendure/dashboard';
import { CheckCircle2 } from 'lucide-react';

export const ValidatedInputComponent: DashboardFormComponent = ({
    value,
    onChange,
    onBlur,
    disabled,
    name,
}) => {
    const { getFieldState } = useFormContext();
    const fieldState = getFieldState(name);

    console.log(fieldState);
    // will log something like this:
    // {
    //     "invalid": false,
    //     "isDirty": false,
    //     "isValidating": false,
    //     "isTouched": false
    // }
    // You can use this data to display validation errors, etc.

    return (
        <div className="space-y-2">
            <Input
                value={value || ''}
                onChange={e => onChange(e.target.value)}
                onBlur={onBlur}
                disabled={disabled}
                className={fieldState.error ? 'border-destructive' : ''}
            />

            {fieldState.error && (
                <Alert variant="destructive">
                    <AlertDescription>{fieldState.error.message}</AlertDescription>
                </Alert>
            )}

            {fieldState.isTouched && !fieldState.error && (
                <div className="flex items-center gap-1 text-sm text-green-600">
                    <CheckCircle2 className="h-4 w-4" />
                    Valid input
                </div>
            )}
        </div>
    );
};
```

:::tip\[Best Practices]

1. **Always use Shadcn UI components** from the `@vendure/dashboard` package for consistent styling
2. **Handle React Hook Form events properly** - call `onChange` and `onBlur` appropriately
3. **Display validation errors** from `fieldState.error` when they exist
4. **Use dashboard design tokens** - leverage `text-destructive`, `text-muted-foreground`, etc.
5. **Provide clear visual feedback** for user interactions
6. **Handle disabled states** by using the `disabled` prop
7. **Target native field overrides precisely** using `pageId`, `blockId`, and `field`

:::

:::important Design System Consistency
Always import UI components from the `@vendure/dashboard` package rather than creating custom inputs or buttons. This ensures your components follow the dashboard's design system and remain consistent with future updates.
:::

Together, custom field components and native detail-page field overrides give you complete control over how data is presented and edited in the Dashboard, while maintaining integration with React Hook Form and the Dashboard design system.

## Nested Forms and Event Handling

When creating custom form components that contain their own forms (e.g., dialogs with forms inside detail pages), you need to prevent form submission events from bubbling up to parent forms. The dashboard provides the `handleNestedFormSubmit` utility for this purpose.

### Why Use handleNestedFormSubmit?

Detail pages in the dashboard are themselves forms. If you add a custom component with its own form (like a dialog with create/edit functionality), submitting the inner form will also trigger the outer detail page form submission. This can cause:

* Unintended save operations on the detail page
* Validation errors on unrelated fields
* Loss of unsaved changes in the dialog

### Using handleNestedFormSubmit

The `handleNestedFormSubmit` utility prevents event propagation and properly handles form submission:

```tsx title="src/plugins/my-plugin/dashboard/components/nested-form-dialog.tsx"
import {
    Button,
    Dialog,
    DialogContent,
    DialogTrigger,
    Form,
    DashboardFormComponent,
    handleNestedFormSubmit,
    useForm,
} from '@vendure/dashboard';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const formSchema = z.object({
    title: z.string().min(1, 'Title is required'),
    description: z.string().min(1, 'Description is required'),
});

type FormData = z.infer<typeof formSchema>;

export const NestedFormDialogComponent: DashboardFormComponent = props => {
    const form = useForm<FormData>({
        resolver: zodResolver(formSchema),
        defaultValues: {
            title: '',
            description: '',
        },
    });

    const onSubmit = (data: FormData) => {
        // Handle your form submission logic
        console.log('Form submitted:', data);
        // You might update the parent form value here
        props.onChange(data);
        form.reset();
    };

    return (
        <Dialog>
            <DialogTrigger render={<Button variant="outline" />}>Open Form</DialogTrigger>
            <DialogContent>
                <Form {...form}>
                    {/* Use handleNestedFormSubmit to prevent event bubbling */}
                    <form onSubmit={handleNestedFormSubmit(form, onSubmit)}>
                        {/* Your form fields here */}
                        <Button type="submit">Save</Button>
                    </form>
                </Form>
            </DialogContent>
        </Dialog>
    );
};
```

### What handleNestedFormSubmit Does

The utility function:

1. Prevents the submit event from propagating to parent forms (`e.stopPropagation()`)
2. Prevents the browser's default form submission behavior (`e.preventDefault()`)
3. Properly triggers react-hook-form's handleSubmit with your custom handler
4. Maintains type safety with TypeScript generics

### When to Use It

Use `handleNestedFormSubmit` whenever you have:

* A dialog with a form inside a detail page
* A custom component with its own form that's nested within another form
* Any scenario where form submission events should not bubble up to parent forms

## Relation Selector Components

The dashboard includes powerful relation selector components for selecting related entities with built-in search and pagination:

```tsx title="src/plugins/my-plugin/dashboard/components/product-selector.tsx"
import {
    SingleRelationInput,
    createRelationSelectorConfig,
    graphql,
    DashboardFormComponentProps,
} from '@vendure/dashboard';

const productConfig = createRelationSelectorConfig({
    listQuery: graphql(`
        query GetProductsForSelection($options: ProductListOptions) {
            products(options: $options) {
                items {
                    id
                    name
                }
                totalItems
            }
        }
    `),
    idKey: 'id',
    labelKey: 'name',
    placeholder: 'Search products...',
    buildSearchFilter: (term: string) => ({
        name: { contains: term },
    }),
});

export function ProductSelectorComponent({ value, onChange }: DashboardFormComponentProps) {
    return <SingleRelationInput value={value} onChange={onChange} config={productConfig} />;
}
```

Features include:

* **Real-time search** with debounced input
* **Infinite scroll pagination** loading 25 items by default
* **Single and multi-select modes** with type safety
* **Customizable GraphQL queries** and search filters
* **Built-in UI components** using the dashboard design system

## Further Reading

For detailed examples of reusable input components, see these dedicated guides:

* **[Input component examples](/current/core/extending-the-dashboard/custom-form-components/form-component-examples)** - Detailed examples of how to use the APIs available for custom form components.
* **[Relation selector components](/current/core/extending-the-dashboard/custom-form-components/relation-selectors)** - Build powerful entity selection components with search, pagination, and multi-select capabilities for custom fields and form inputs