Custom Form Elements

The dashboard allows you to create custom form elements that provide complete control over how data is rendered and how users interact with forms. This includes:

Custom Field Components — Globally-registered components that can be used to render custom fields and configurable operation arguments
Detail Form Components — Form input components that target specific fields of detail pages

Anatomy of a Form Component

All form components must implement the DashboardFormComponent type.

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.

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

src/plugins/my-plugin/dashboard/components/color-picker.tsx

import { Button, Card, CardContent, cn, DashboardFormComponent, Input } from '@vendure/dashboard';import { useState } from 'react';import { useFormContext } from 'react-hook-form';// By typing your component as DashboardFormComponent, the props will be correctly typedexport 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:

Custom Field Components

Let's configure a custom field which uses the ColorPickerComponent as its form component.

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

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.

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 component. For example, we can add a color code to a shipping calculator:

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) => {        // ...    },});

Detail Form Components

Detail form components allow you to replace specific input fields in existing dashboard forms with custom implementations. They are targeted to specific pages, blocks, and fields.

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

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:

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

Input components are targeted using three properties:

pageId: The ID of the page (e.g., 'product-detail', 'customer-detail')
blockId: The ID of the form block (e.g., 'product-form', 'customer-info')
field: The name of the field to replace (e.g., 'price', 'email')

Tsx

inputs: [    {        pageId: 'product-variant-detail',        blockId: 'main-form',        field: 'price',        component: PriceInputComponent,    },    {        pageId: 'customer-detail',        blockId: 'main-form',        field: 'emailAddress',        component: EmailInputComponent,    },];

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

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

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.

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.

src/plugins/my-plugin/dashboard/components/validated-input.tsx

import { DashboardFormComponent, Input, Alert, AlertDescription } from '@vendure/dashboard';import { useFormContext } from 'react-hook-form';import { CheckCircle2 } from 'lucide-react';export const ValidatedInputComponent: DashboardFormComponent = ({ value, onChange, 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={field.value || ''}                onChange={e => field.onChange(e.target.value)}                onBlur={field.onBlur}                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>    );}

Best Practices

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

:::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. :::

The unified custom form elements system gives you complete flexibility in how data is presented and edited in the dashboard, while maintaining seamless integration with React Hook Form and the dashboard's 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:

src/plugins/my-plugin/dashboard/components/nested-form-dialog.tsx

import {    Button,    Dialog,    DialogContent,    DialogTrigger,    Form,    DashboardFormComponent,    handleNestedFormSubmit} from '@vendure/dashboard';import { useForm } from 'react-hook-form';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 asChild>                <Button variant="outline">Open Form</Button>            </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:

Prevents the submit event from propagating to parent forms (e.stopPropagation())
Prevents the browser's default form submission behavior (e.preventDefault())
Properly triggers react-hook-form's handleSubmit with your custom handler
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 Selectors

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

src/plugins/my-plugin/dashboard/components/product-selector.tsx

import {    SingleRelationInput,    createRelationSelectorConfig,    graphql,    CustomFormComponentInputProps,} 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 }: CustomFormComponentInputProps) {    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