The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.
TypeScript b2b-marketplacecomposable-commerceecommerceenterpriseheadless-commercemarketplacemedusamedusajsmulti-vendortypescript
---
title: "How to Extend Forms and Tables"
sidebarTitle: "Extend Forms & Tables"
description: "Add validated fields, detail-section displays, and list columns to a built-in model from a single file with defineCustomFieldsConfig."
---
`defineCustomFieldsConfig` is Mercur's model-scoped extension surface. From one file per model you add validated fields to built-in create and edit forms, replace, remove, or add fields in detail sections, and add columns to the list table. Everything wires into the built-in page and stays typed against the model's generated registry.
<Info>
**UI, not schema.** This helper is a panel surface. It renders, validates, and displays fields. It does not create database columns. To store extra data, use the backend [Custom Fields module](/rc/resources/customization/custom-fields) or your own API route or workflow. In the MVP, panel custom fields for `product` are submitted under `additional_data` and persisted onto the product's `metadata`.
</Info>
## What you'll build
An `ERP ID` field on the vendor product edit form, shown in the product's detail section and as a list-table column, all from a single `src/custom-fields/product.tsx`.
## Register the typed targets
Models, form zones, display zones, and built-in field ids are typed per panel. You register them once, and `create-mercur-app` ships this reference for you.
```typescript apps/vendor/src/extension-targets.d.ts
/// <reference types="@mercurjs/vendor/extension-targets" />
```
## Build the config
<Steps>
<Step title="Create the model file">
Drop `src/custom-fields/<model>.tsx` and default-export a `defineCustomFieldsConfig`. `createFormHelper` from `@mercurjs/dashboard-shared` turns a Zod schema into an input type plus validation.
```tsx apps/vendor/src/custom-fields/product.tsx
import { defineCustomFieldsConfig } from "@mercurjs/dashboard-sdk"
import { createFormHelper } from "@mercurjs/dashboard-shared"
type ProductWithMeta = { metadata?: Record<string, unknown> }
const form = createFormHelper<ProductWithMeta>()
export default defineCustomFieldsConfig({
model: "product",
forms: [
{
zone: "edit",
fields: {
erp_id: form.define({
validation: form.string().optional(),
label: "ERP ID",
description: "External system identifier",
placeholder: "ERP-000",
defaultValue: (data) => (data?.metadata?.erp_id as string) ?? "",
}),
},
},
],
})
```
</Step>
<Step title="Add a detail-section display">
`displays[]` targets a detail-page section by its `zone` id. Keyed by field `id`, an entry adds, replaces, or removes a field.
```tsx apps/vendor/src/custom-fields/product.tsx
import { Text } from "@medusajs/ui"
// ...inside defineCustomFieldsConfig:
displays: [
{
zone: "general",
fields: [
// ADD: an unknown id appends a new read-only row
{
id: "erp_id",
component: ({ data }) => (
<Text size="small" className="text-ui-fg-subtle px-6 py-4">
ERP ID: {String(data?.metadata?.erp_id ?? "-")}
</Text>
),
},
// REMOVE: a built-in id + null hides the field
{ id: "subtitle", component: null },
// REPLACE: a built-in id + component overrides its render
{
id: "handle",
component: ({ data }) => (
<Text size="small" className="text-ui-fg-subtle px-6 py-4">
/{(data as { handle?: string })?.handle}
</Text>
),
},
],
},
],
```
<Tip>
Built-in field ids such as `subtitle`, `handle`, `status`, and `title` autocomplete from the panel's generated `CustomFieldsRegistry`. An unknown id is treated as an added row.
</Tip>
</Step>
<Step title="Add a list column">
The `list` block extends the model's list table. Add or override columns by id, hide built-in columns, and reorder.
```tsx apps/vendor/src/custom-fields/product.tsx
// ...inside defineCustomFieldsConfig:
list: {
columns: [
{
id: "erp_id",
header: "ERP",
component: ({ row }) => String(row.metadata?.erp_id ?? "-"),
},
],
viewDefaults: {
columnVisibility: { collection: false }, // hide a built-in column
columnOrder: ["product", "erp_id", "status"], // reorder
},
},
```
</Step>
<Step title="Reload the panel">
Open the vendor portal. The product edit drawer shows the ERP ID field, validated on submit and persisted via `additional_data`. The detail general section shows the ERP ID row, with `subtitle` removed and `handle` re-rendered. The product list shows the ERP column.
</Step>
</Steps>
## The createFormHelper surface
`createFormHelper<T>()` exposes a Zod-based surface that drives both the input type and its validation.
```ts
const form = createFormHelper<T>()
form.define({
validation: form.string().min(1), // string | number | boolean | date | array | object | null | nullable | coerce
label: "…",
description: "…",
placeholder: "…",
defaultValue: "" | ((data) => /* derive from the entity */),
component, // optional custom render component
})
```
Fields render through the standard `Form.Field → Form.Item` chain, never a raw `Controller`. They participate in the existing `TabbedForm` and `RouteDrawer` submit and validation flow.
## Linked-module data
To read data from a linked module alongside the entity, declare it with `link`. Those relations are fetched with the entity and become available to columns and displays.
```ts
export default defineCustomFieldsConfig({
model: "product",
link: "brand", // or ["brand", "warranty"]
list: {
columns: [{ id: "brand_name", header: "Brand", component: ({ row }) => row.brand?.name }],
},
})
```
<Note>
The SDK derives the fetch query from `link` and merges it into the built-in query with the `+` and `-` convention. You never hand-write the field list.
</Note>
## Verify
1. The ERP ID field renders in the product edit drawer and validates on submit.
2. Saving persists the value, visible on reload, via `additional_data` to `metadata`.
3. The detail general section shows the ERP row, hides `subtitle`, and re-renders `handle`.
4. The product list shows the ERP column, hides `collection`, and reorders columns.
5. Set `zone: "nope"` in `forms`. `bun run lint` (tsc) fails against the model's registry.
## FAQ
<AccordionGroup>
<Accordion title="Which models and zones are available?">
Today: the `product` model in the vendor portal, with form zone `edit` and display zone `general`. The valid set per panel is generated into `CustomFieldsRegistry` in `extension-targets.d.ts`. Autocomplete `model` and `zone` to see what's mounted.
</Accordion>
<Accordion title="Where is the value actually stored?">
In the MVP, product custom fields are submitted under `additional_data` and persisted onto `product.metadata`. `defineCustomFieldsConfig` itself doesn't create a column. For durable, queryable storage, model it with the backend [Custom Fields module](/rc/resources/customization/custom-fields) or a custom route or workflow.
</Accordion>
<Accordion title="Can I extend the onboarding wizard?">
That's the same helper with `zone: "onboarding"` and `tab` set to a wizard step id (vendor only). It's designed but not mounted in the current MVP. The runtime host exists. The wizard mount is a follow-up.
</Accordion>
<Accordion title="Can a block ship custom fields?">
Yes. A [block](/rc/learn/blocks) can include `src/custom-fields/` files in its `vendor_ui` or `admin_ui` entry, aggregated like the host app's.
</Accordion>
</AccordionGroup>
## Next steps
<CardGroup cols={2}>
<Card title="Custom Fields module" href="/rc/resources/customization/custom-fields">
Persist extra data on an entity with a generated side table.
</Card>
<Card title="Add a widget" href="/rc/resources/tutorials/add-a-widget">
Inject a component at a built-in zone.
</Card>
</CardGroup>