Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Teach the two real custom-form-field flows in the docs
Damian Legawiec072c0925d89b
diff --git a/docs/developer/dashboard/customization/quickstart.mdx b/docs/developer/dashboard/customization/quickstart.mdxindex d5070a9fa2..40d1fd0c9f 100644--- a/docs/developer/dashboard/customization/quickstart.mdx+++ b/docs/developer/dashboard/customization/quickstart.mdx@@ -87,7 +87,7 @@ Every `key` must be unique, including against the built-ins (`getting-started`,## What just happened-`defineDashboardPlugin` registers extensions against the dashboard's shared registries: `nav`, `routes`, `slots`, `tables`, and `settingsNav`. Your `src/plugins.ts` runs when the app boots (the starter's `main.tsx` imports it), so everything is registered before the first render. These are the exact same APIs distributable plugins use — the only difference is packaging.+`defineDashboardPlugin` registers extensions against the dashboard's shared registries: `nav`, `routes`, `slots`, `tables`, `settingsNav`, `formFields`, and `customFieldComponents`. Your `src/plugins.ts` runs when the app boots (the starter's `main.tsx` imports it), so everything is registered before the first render. These are the exact same APIs distributable plugins use — the only difference is packaging.The custom route mounts under `/<store id>/analytics`. Routes registered this way are matched at navigation time, so they can even be registered lazily after boot.diff --git a/docs/developer/dashboard/customization/slots.mdx b/docs/developer/dashboard/customization/slots.mdxindex 8e8584b191..89c6d01b31 100644--- a/docs/developer/dashboard/customization/slots.mdx+++ b/docs/developer/dashboard/customization/slots.mdx@@ -74,6 +74,21 @@ function AdminOnlyMenuItem() {The entry-level `if` predicate also exists, but it only receives the slot's own context (the same props your component gets) — use it to skip an entry based on the host page's data, e.g. `if: ({ product }) => !!product.brand_id`. When it returns `false`, the entry is skipped entirely (no DOM nodes mounted).+## Binding to the host form++Slots on form pages (product, category, store settings — see the [slots catalog](/developer/dashboard/slots-catalog#detail-page-form-slots) for which) render **inside the page's `<form>`** and expose its react-hook-form instance. A widget can register inputs against it with `useHostForm()` — they hydrate from the API, flip the Save button on change, and persist in the page's own save, with no save logic in the widget:++```tsx+import { useHostForm } from '@spree/dashboard-core'++function TechSpecsCard() {+ const form = useHostForm<{ tech_specs: string }>()+ return <Textarea {...form.register('tech_specs')} />+}+```++Pair it with a `formFields` registration so the field hydrates and ships in the payload — the full walkthrough is the [custom form field recipe](/developer/dashboard/recipes/custom-form-field). Never render your own `<form>` inside a slot on these pages: HTML forbids nested forms, and the host form already owns submission. On pages without a host form (orders, customers), `useHostForm()` throws — use `useOptionalHostForm()` and fall back to your own state + API save.+## Position`position` controls render order within the slot. Built-in entries (when the dashboard ships any) use 100/200/300 to leave gaps. Default is 100, so two entries with no explicit position render in registration order.diff --git a/docs/developer/dashboard/public-api.mdx b/docs/developer/dashboard/public-api.mdxindex 591fcec2fd..39d57ffae8 100644--- a/docs/developer/dashboard/public-api.mdx+++ b/docs/developer/dashboard/public-api.mdx@@ -16,7 +16,7 @@ Default-import surface for plugins and customizations.import { defineDashboardPlugin } from '@spree/dashboard-core'```-Single declarative entry-point for all five registries. See [Customization Quickstart](/developer/dashboard/customization/quickstart) for the full shape.+Single declarative entry-point for every registry. See [Customization Quickstart](/developer/dashboard/customization/quickstart) for the full shape.### Registries@@ -35,10 +35,14 @@ import {useSlotEntries,// table registrytables,+ // extension fields on built-in forms (hydrate + save with the host form)+ formFields,+ // input components for specific custom field definitions+ customFieldComponents,} from '@spree/dashboard-core'```-Each registry exposes `add`/`remove`/`update`/`insertBefore`/`insertAfter` mutators. See the per-feature pages for examples.+Each registry exposes `add`/`remove`/`update`-style mutators. See the per-feature pages for examples — form fields and custom field components are covered in the [custom form field recipe](/developer/dashboard/recipes/custom-form-field).### Components@@ -89,6 +93,8 @@ import {useDirectUpload, // ActiveStorage direct uploadsuseExport, // CSV export job lifecycleuseResourceMutation, // useMutation wrapper with 422 handling+ useHostForm, // the built-in form a slot widget renders inside (throws when absent)+ useOptionalHostForm, // same, but null when the page has no host form} from '@spree/dashboard-core'```diff --git a/docs/developer/dashboard/recipes/custom-form-field.mdx b/docs/developer/dashboard/recipes/custom-form-field.mdxindex ec9a0034d7..5ecea89706 100644--- a/docs/developer/dashboard/recipes/custom-form-field.mdx+++ b/docs/developer/dashboard/recipes/custom-form-field.mdx@@ -1,21 +1,66 @@----title: Add a custom field to the product page+title: Add a custom field to the product formsidebarTitle: Custom form field-description: Surface a custom product attribute on the product detail page — edit it in a sidebar card, validate it, and persist via the Admin API.+description: Add a field to the built-in product form that hydrates from the API and saves with the form's own Save button — no save logic of your own.----The dashboard's product form lives in `@spree/dashboard` and renders core attributes (name, description, price, …). When you've added a custom column to `spree_products` or a custom field through a [metafield definition](/developer/customization/metadata), you'll want to edit it on the same page. This recipe adds a **self-contained editor card** to the product page's sidebar: it owns its own small form and saves through the Admin API.+Two ways to get a custom field onto the product form, both saved by the page's single Save button:-<Note>-Slot widgets are additive — the built-in product form doesn't expose its internal form instance to slots, so your card manages its own state and its own save. That's a feature: your field can't break the core form, and it works identically from a host app or a distributed plugin.-</Note>+- **Custom field definition (no code)** — declare the field as data; the dashboard renders it. Right for merchant-managed attributes and most plugin data.+- **Extension form field (code)** — for a real database column your plugin added to `spree_products`. You register the field and render its input; hydration and saving stay with the host form.-## Backend prerequisites+## Path A: custom field definition — no code-This recipe assumes you've added the column or metafield on the Rails side:+Create a definition for products (Settings → Custom fields, the in-place "Set up" button on the Custom Fields card, or the API):++```bash+npx spree api post custom_field_definitions --data '{+ "resource_type": "Spree::Product",+ "namespace": "specs",+ "key": "tech_specs",+ "label": "Technical specifications",+ "field_type": "long_text"+}'+```++That's the whole feature. The **Custom Fields card** on the product form now renders a textarea for it; the value rides the form's `custom_fields[]` and persists when the merchant hits **Save**. Field types: `short_text`, `long_text`, `rich_text`, `number`, `boolean`, `json`.++### Optional: replace the input widget++When the default widget isn't right — a color, a rating, a structured pair — register a component for that specific definition, keyed by its `namespace.key`:++```tsx+// src/plugins.ts (or a plugin's entry module)+import { type CustomFieldComponentProps, defineDashboardPlugin } from '@spree/dashboard-core'++function ColorPicker({ id, value, onChange, ariaLabel }: CustomFieldComponentProps) {+ return (+ <input+ id={id}+ type="color"+ aria-label={ariaLabel}+ value={(value as string) || '#000000'}+ onChange={(e) => onChange(e.target.value)}+ />+ )+}++defineDashboardPlugin({+ customFieldComponents: {+ 'specs.color': ColorPicker,+ },+})+```++The component is a controlled input — render `value`, call `onChange`. Persistence stays with the card (the form's Save on products and categories; the card's own Save on orders and customers). When no component is registered, the default widget for the definition's `field_type` renders.++## Path B: extension form field — a real column++Use this when your plugin adds an actual column and API attribute.++### 1. Backend```ruby-# A migration:class AddTechSpecsToSpreeProducts < ActiveRecord::Migration[7.2]def changeadd_column :spree_products, :tech_specs, :text, null: false, default: ''@@ -23,72 +68,42 @@ class AddTechSpecsToSpreeProducts < ActiveRecord::Migration[7.2]end```-And declared it as a permitted attribute on the Admin API serializer + controller (see [Backend integration](/developer/dashboard/customization/backend)).+Expose it on the Admin API — the serializer returns `tech_specs`, and the products controller permits it on write (see [Backend integration](/developer/dashboard/customization/backend)). Read and write names must match.-## 1. Register the card+### 2. Register the field-Inject it into the product form's sidebar via a slot:+Tell the product form about the field: where its value comes from on load. Everything else — dirty tracking, the PATCH payload, re-baselining after save — is the host form's job.```tsx-// src/plugins.ts (in your dashboard app)+// src/plugins.ts (or a plugin's entry module)import { defineDashboardPlugin } from '@spree/dashboard-core'-import { TechSpecsCard } from './fields/tech-specs-card'defineDashboardPlugin({- slots: {- 'product.form_sidebar': [{- id: 'tech-specs',- component: TechSpecsCard as never,- position: 80,- }],+ formFields: {+ product: [+ // `from` receives the fetched product — or null on the create form.+ { name: 'tech_specs', from: (product) => product?.tech_specs ?? '' },+ ],},})```-If you don't see a slot at the right spot in the form, see [Slots catalog](/developer/dashboard/slots-catalog) — if one's missing, open a PR adding it.--## 2. Build the card+### 3. Render the input from a slot-The slot's context is `{ product }` — the product being edited. The card seeds its own React Hook Form instance from it and saves with its own button:+The `product.form_sidebar` slot renders inside the product form. Bind your input to the host form with `useHostForm()` — no `<form>` of your own, no save button:```tsx// src/fields/tech-specs-card.tsx-import { adminClient, mapSpreeErrorsToForm, useResourceMutation } from '@spree/dashboard-core'+import { useHostForm } from '@spree/dashboard-core'import {- Button,- Card, CardContent, CardFooter, CardHeader, CardTitle,+ Card, CardContent, CardHeader, CardTitle,Field, FieldError, FieldLabel, Textarea,} from '@spree/dashboard-ui'-import { useForm } from 'react-hook-form'import { useTranslation } from 'react-i18next'-interface Props {- product: { id: string; tech_specs?: string }-}--interface FormValues {- tech_specs: string-}--export function TechSpecsCard({ product }: Props) {+export function TechSpecsCard() {const { t } = useTranslation()- const form = useForm<FormValues>({- defaultValues: { tech_specs: product.tech_specs ?? '' },- })-- const update = useResourceMutation({- mutationFn: (values: FormValues) => adminClient.products.update(product.id, values),- invalidate: [['products']],- })-- async function onSubmit(values: FormValues) {- try {- await update.mutateAsync(values)- } catch (err) {- if (!mapSpreeErrorsToForm(err, form.setError)) throw err- }- }-+ const form = useHostForm<{ tech_specs: string }>()const error = form.formState.errors.tech_specs?.messagereturn (@@ -96,81 +111,60 @@ export function TechSpecsCard({ product }: Props) {<CardHeader><CardTitle>{t('admin.fields.product.tech_specs.label')}</CardTitle></CardHeader>- <form onSubmit={form.handleSubmit(onSubmit)}>- <CardContent>- <Field>- <FieldLabel className="sr-only" htmlFor="tech_specs">- {t('admin.fields.product.tech_specs.label')}- </FieldLabel>- <Textarea- id="tech_specs"- rows={6}- placeholder={t('admin.fields.product.tech_specs.placeholder')}- aria-invalid={Boolean(error)}- {...form.register('tech_specs', {- maxLength: { value: 5000, message: t('admin.fields.product.tech_specs.too_long') },- })}- />- {error && <FieldError>{error}</FieldError>}- </Field>- </CardContent>- <CardFooter>- <Button type="submit" size="sm" disabled={update.isPending || !form.formState.isDirty}>- {t('admin.common.save')}- </Button>- </CardFooter>- </form>+ <CardContent>+ <Field>+ <FieldLabel className="sr-only" htmlFor="tech_specs">+ {t('admin.fields.product.tech_specs.label')}+ </FieldLabel>+ <Textarea+ id="tech_specs"+ rows={6}+ placeholder={t('admin.fields.product.tech_specs.placeholder')}+ aria-invalid={Boolean(error)}+ {...form.register('tech_specs')}+ />+ {error && <FieldError>{error as string}</FieldError>}+ </Field>+ </CardContent></Card>)}```-A few patterns worth flagging:--- **`invalidate: [['products']]`** refetches the product queries after a save, so the page (and list views) pick up the new value.-- **`mapSpreeErrorsToForm`** routes a 422 (e.g. a server-side length validation) onto the field as an inline error; `useResourceMutation` already suppresses its toast for validation failures.-- **Disable save until dirty** — `form.formState.isDirty` keeps the button inert when nothing changed.-- **Use the field-key i18n convention** — `admin.fields.product.tech_specs.{label,placeholder}`; see [Translations](/developer/dashboard/customization/translations#field-key-convention).-- **Apply `aria-invalid`** when the field has an error so screen readers announce it.--## 3. Translations--```json-// src/locales/en.json — note the top-level "admin" wrapper-{- "admin": {- "fields": {- "product": {- "tech_specs": {- "label": "Technical specifications",- "placeholder": "RAM, CPU, dimensions, weight…",- "too_long": "Keep it under 5000 characters"- }- }- }- }-}+```tsx+// src/plugins.ts — alongside the formFields registration+defineDashboardPlugin({+ formFields: {+ product: [{ name: 'tech_specs', from: (product) => product?.tech_specs ?? '' }],+ },+ slots: {+ 'product.form_sidebar': [{ id: 'tech-specs', component: TechSpecsCard as never, position: 80 }],+ },+})```-```ts-// src/plugins.ts — before the defineDashboardPlugin call-import { i18n } from '@spree/dashboard-core'-import en from './locales/en.json'+Done. The field hydrates when the page loads, participates in the form's dirty state (Save enables when it changes), ships in the same PATCH as every core field, and re-baselines after save.-i18n.addResourceBundle('en', 'translation', en, true, true)-```+### Validation++Extension fields are validated by the **server** — a Rails validation failing returns a 422, and the host form's error mapping puts the message inline on your field (that's the `errors.tech_specs` read in the component). This mirrors how Vendure and Saleor treat extension-field validation: the backend is authoritative; the client renders what it says.++### Which forms support this-See [Translations](/developer/dashboard/customization/translations) for locales beyond English.+`useHostForm()` works wherever a built-in form exposes its form context — currently the **product** (edit + new), **category** (edit + new), and **store settings** forms, with matching slots (`product.form_sidebar`, `category.form_sidebar`, `store.form_main`) and form keys (`product`, `category`, `store`). Orders and customers have no page-wide form — their sheets own their edits — so slot widgets there manage their own persistence; use `useOptionalHostForm()` to write a widget that adapts to both contexts.-## What you should *not* do+## Which path should I pick?-- **Don't mirror the value into `useState` alongside RHF.** The card's form instance owns it; duplicate state goes out of sync after a save or reset.-- **Don't write to the core form's fields from your card.** The built-in form saves core attributes; your card saves yours. Two independent submits can't clobber each other.-- **Don't skip the server-side validation.** The client-side `maxLength` is UX; the Rails validation is the contract.+| Situation | Path |+|---|---|+| Merchant-defined attributes, plugin data without schema migrations | **A** — definition, zero code |+| Default widget is fine | **A** |+| A real column with Rails validations, queries, or indexes | **B** |+| The field belongs visually inside your own card with other UI | **B** |## Reference-- [React Hook Form `useForm`](https://react-hook-form.com/docs/useform)-- [`mapSpreeErrorsToForm`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/form-errors.ts) — wires 422 responses to field errors-- [`useResourceMutation`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/hooks/use-resource-mutation.ts)-- [Field-key i18n convention](/developer/dashboard/customization/translations#field-key-convention)+- [Custom fields](/developer/customization/metadata) — definitions, types, the API+- [Slots](/developer/dashboard/customization/slots) — the injection mechanism+- [`useHostForm`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/hooks/use-host-form.ts)+- [`formFields` registry](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/form-fields-registry.ts)diff --git a/docs/developer/dashboard/slots-catalog.mdx b/docs/developer/dashboard/slots-catalog.mdxindex 919e0c614d..f3d25df926 100644--- a/docs/developer/dashboard/slots-catalog.mdx+++ b/docs/developer/dashboard/slots-catalog.mdx@@ -43,9 +43,11 @@ Rendered by `<PageHeader>` (`@spree/dashboard-core/components/page-header.tsx`)| Use | Add menu items (`<DropdownMenuItem>`) for secondary actions || Context | `{ resource, ...slotContext }` — same as `page.actions` |-## Detail-page sidebar slots+## Detail-page form slots-The product, order, and customer detail pages each render a slot at the bottom of their right-hand sidebar, below the built-in cards. The context key matches the resource name.+The resource detail pages each render a slot below their built-in cards. The context key matches the resource name.++**Host form:** on pages marked *host form: yes*, the slot renders inside the page's own `<form>` and the form context is exposed — widgets can bind inputs via [`useHostForm()`](/developer/dashboard/recipes/custom-form-field) that hydrate, dirty-track, and save with the page's Save button. On pages without one, widgets own their persistence (use `useOptionalHostForm()` to adapt).### `product.form_sidebar`@@ -53,6 +55,23 @@ The product, order, and customer detail pages each render a slot at the bottom o|---|---|| Use | Add a card scoped to the product being edited (e.g., a "Brand" picker, wishlist stats, sync status from an external system) || Context | `{ product }` — the full `Product` record from the Admin API |+| Host form | **Yes** — form key `product` |++### `category.form_sidebar`++| Where | Category detail page (`products/categories/$categoryId`), end of the sidebar column |+|---|---|+| Use | Category-scoped cards — merchandising rules, feed settings, external sync state |+| Context | `{ category }` — the `Category` record (may be briefly `undefined` while refetching) |+| Host form | **Yes** — form key `category` |++### `store.form_main`++| Where | Store settings page (`settings/store`), end of the main column |+|---|---|+| Use | Store-level settings a plugin owns — integration toggles, account linking |+| Context | `{ store }` — the full `Store` record |+| Host form | **Yes** — form key `store` |### `order.form_sidebar`@@ -60,6 +79,7 @@ The product, order, and customer detail pages each render a slot at the bottom o|---|---|| Use | Fraud-check status, shipping-integration state, loyalty points earned || Context | `{ order }` — the full `Order` record |+| Host form | No — widgets save via their own API calls |### `customer.form_sidebar`@@ -67,6 +87,7 @@ The product, order, and customer detail pages each render a slot at the bottom o|---|---|| Use | Loyalty status, support-ticket summary, external CRM links || Context | `{ customer }` — the full `Customer` record |+| Host form | No — the page edits through sheets; widgets save via their own API calls |## Page tabs slot