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
---
title: Slots catalog
sidebarTitle: Slots catalog
description: Every named slot the dashboard renders today. Each entry lists the host page, the slot name, and the context the slot's components receive.
---
This is the canonical list of slots the admin dashboard and the seller panel currently expose. The source of truth is the `<Slot name="…">` call sites in the dashboard source (linked under Reference below); each entry here records the host page, the slot name, and the context your component receives.
If you need a new injection point in a built-in page, open a PR adding `<Slot name="..." context={...} />` and a documentation entry here — that's the contract for new slots.
## At a glance
| Area | Page | Slots |
|---|---|---|
| Every page | Page header | `page.actions`, `page.actions_dropdown` |
| Every page | Tabbed sub-navigation | `page.tabs` |
| Products | Product | `product.form_main`, `product.form_sidebar`, `product.media.*`, `product.variant.form_fields` |
| Products | Media library | `media.form_fields`, `media.context_menu` |
| Products | Category | `category.form_main`, `category.form_sidebar` |
| Products | Collection | `collection.form_main`, `collection.form_sidebar` |
| Products | Catalog | `catalog.form_sidebar` |
| Products | Price list | `price_list.form_sidebar`, `price_list.rule_form.<type>` |
| Orders | Order | `order.form_main`, `order.form_sidebar` |
| Customers | Customer | `customer.form_main`, `customer.form_sidebar` |
| Customers | Company | `company.form_main`, `company.form_sidebar`, `company_membership.*` |
| Promotions | Promotion | `promotion.form_sidebar`, `promotion.rule_form.<type>`, `promotion.action_form.<type>` |
| Inventory | Purchase order | `purchase_order.form_main`, `purchase_order.form_sidebar` |
| Inventory | Stock transfer | `stock_transfer.form_main`, `stock_transfer.form_sidebar` |
| Sellers | Seller | `seller.form_main`, `seller.form_sidebar` |
| Sellers | Seller payout | `seller_payout.form_main`, `seller_payout.form_sidebar` |
| Settings | Store | `store.form_main` |
| Settings | Delivery profile | `delivery_profile.form_main`, `delivery_profile.form_sidebar` |
| Settings, options, customer groups | Create and edit sheets | `<resource>.form_fields` — see [Sheet slots](#sheet-slots) |
| Settings | Payment method | `payment_method.*.<provider>` |
| Settings | Webhook endpoint | `webhook_endpoint.form_sidebar` |
| Onboarding | Getting started | `getting-started.task.<name>` |
| Sign-in | Login page | `login.after` |
| Sign-in | Store selection | `store_selection` |
| Sign-in | No store access | `no_store_access` |
| Seller panel | Product, order, payout, profile, team | `seller.product.*`, `seller.order.*`, `seller.payout.*`, `seller.profile.*`, `seller.team.*` |
## Ambient context
Ambient context (`permissions`, `store`, `user` merged into every slot's props) is planned but **not wired up yet** — today slot components receive only the slot-specific context listed below. Until it lands, read those values with the hooks instead:
```tsx
import { usePermissions, useStore } from '@spree/dashboard'
function MyWidget({ product }: { product: Product }) {
const { permissions } = usePermissions()
const { store } = useStore()
if (!permissions.can('read', 'loyalty_record')) return null
// ...
}
```
The same applies to an entry's `if` predicate: it receives the slot context, but not `permissions` — gate inside the component for now.
## Page header slots
Rendered by `<PageHeader>` (`@spree/dashboard-core/components/page-header.tsx`) at the top of every detail and list page that uses the shared chrome.
### `page.actions`
| Where | Top-right of `<PageHeader>`, left of any explicit `actions` prop |
|---|---|
| Use | Add primary action buttons (e.g., a "Refund" button on the order detail page) |
| Context | `{ resource, ...slotContext }` — `resource` is the current page's primary record, when the host passed one to `<PageHeader resource={...} />`. May be `undefined` on list pages. |
### `page.actions_dropdown`
| Where | Inside the more-actions (`⋯`) dropdown menu, above the auto-rendered Copy ID / Delete items |
|---|---|
| Use | Add menu items (`<DropdownMenuItem>`) for secondary actions |
| Context | `{ resource, ...slotContext }` — same as `page.actions` |
## Page tabs slot
### `page.tabs` (default)
Rendered by `<PageTabs>` at the right edge of any tabbed sub-nav.
| Where | After the built-in tab strip |
|---|---|
| Use | Append your own tab(s) to a sub-route — typically for plugin-owned views inside an existing resource (e.g., "Returns" tab on the order detail) |
| Context | `{ tabs, ...slotContext }` — `tabs` is the array of built-in tabs (so you can inspect or filter by them) |
Some pages override `slotName` to scope tabs to a single resource (e.g., `slotName="order.tabs"`). The catalog will grow these as we wire them up; today only the default `page.tabs` name is in production use.
## Detail-page slots
Every resource detail page renders a slot at the end of its sidebar column, and some also at the end of the main column. The slot name starts with the resource name, and the context key matches it.
**Host form.** On pages marked *host form: yes*, the slot renders inside the page's own `<form>` and exposes it — widgets can bind inputs via [`useHostForm()`](/developer/dashboard/recipes/custom-form-field) that hydrate, dirty-track, and save with the page's Save button. The form key is what you register extension fields under in `formFields`. On every other page, widgets own their persistence; use `useOptionalHostForm()` to write a widget that adapts to both.
<Note>
On host-form pages your widget renders inside the page's `<form>` element, so a `<Button>` in it submits the page unless you give it `type="button"`.
</Note>
### Products
#### `product.form_main`
| Where | Product create and edit pages (`products/new`, `products/$productId`), end of the main column |
|---|---|
| Use | Wide cards that belong with the product's content — size charts, bundle contents, a feed preview |
| Context | `{ product, mode }` — `mode` is `'new'` or `'edit'`; `product` is `undefined` while creating |
| Host form | **Yes** — form key `product` |
#### `product.form_sidebar`
| Where | Product create and edit pages (`products/new`, `products/$productId`), end of the sidebar column |
|---|---|
| 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, mode }` — the full `Product` record from the Admin API; `mode` is `'new'` or `'edit'`, and `product` is `undefined` while creating |
| Host form | **Yes** — form key `product` |
#### `product.media.form_fields`
| Where | The media editor sheet on the product create and edit pages, below the built-in fields |
|---|---|
| Use | Fields stored on one media file — a photo credit, a license, a usage restriction |
| Context | `{ productId, media, mediaIndex, fieldPrefix, onSave }` — `media` is the row's form values, `fieldPrefix` the row's path (`media.2`); `productId` is `undefined` while creating; `onSave` works as in `product.variant.form_fields`. The dashboard's own custom fields card renders here |
| Host form | **Yes** — form key `product.media`. Bind inputs under `fieldPrefix` and register fields under `product.media` ([recipe](/developer/dashboard/recipes/custom-form-field#a-field-on-a-media-or-variant-row)) |
#### `product.media.actions`
| Where | The product page's Media card, after the "Add video link" button |
|---|---|
| Use | More ways to add media — import from a digital asset manager, generate an image |
| Context | `{ productId, addMedia }` — `addMedia(entries)` appends entries to the gallery and they save with the product. Each entry carries a `signed_id` (from a finished upload), a library `source_media_id`, or `media_type: 'external_video'` with an `external_video_url`, plus an optional `previewUrl` for the tile |
| Host form | **Yes** — form key `product` |
#### `product.variant.form_fields`
| Where | The variant editor sheet on the product create and edit pages, after the Tax section |
|---|---|
| Use | Fields stored on one variant — a supplier code, a fulfillment flag, a per-variant certification |
| Context | `{ variant, variantIndex, fieldPrefix, onSave }` — `variant` is the row's form values, `fieldPrefix` the row's path (`variants.0`); `onSave(handler)` registers an async function the sheet runs on Done, which keeps the sheet open when it resolves `false`, and returns an unregister function. A widget that writes its own record (as the dashboard's custom fields card does) saves it through `onSave`, so Done keeps it and Cancel drops it |
| Host form | **Yes** — form key `product.variant`. Bind inputs under `fieldPrefix` and register fields under `product.variant` |
#### `media.form_fields`
| Where | Media library (`products/media`), the file's detail sheet, below "Alt text" |
|---|---|
| Use | Fields stored on the file itself — a photo credit, a license, an expiry date for the rights to use it |
| Context | `{ media, canWrite }` — the `Media` record from the Admin API; `canWrite` is whether the admin may edit it |
| Host form | **Yes** — form key `media`. The sheet's Save sends the fields to the media endpoint, which accepts what `Spree::Media.additional_permitted_attributes` declares |
#### `media.context_menu`
| Where | Media library, the right-click menu on a file in the grid, above Delete |
|---|---|
| Use | Actions on one file — open it in a digital asset manager, remove its background, copy a public link |
| Context | `{ media, canWrite }` — render `<ContextMenuItem>`s |
#### `category.form_main`
| Where | Category create and edit pages (`products/categories/new`, `products/categories/$categoryId`), end of the main column |
|---|---|
| Use | Wide category cards — a landing-page banner, a curated content block |
| Context | `{ category, mode }` — `mode` is `'new'` or `'edit'`; `category` is `undefined` while creating (and briefly while refetching) |
| Host form | **Yes** — form key `category` |
#### `category.form_sidebar`
| Where | Category create and edit pages, end of the sidebar column |
|---|---|
| Use | Category-scoped cards — merchandising rules, feed settings, external sync state |
| Context | `{ category, mode }` — as for `category.form_main` |
| Host form | **Yes** — form key `category` |
#### `collection.form_main`
| Where | Collection create and edit pages (`products/collections/new`, `products/collections/$collectionId`), end of the main column |
|---|---|
| Use | Wide collection cards — a campaign banner, a schedule |
| Context | `{ collection, mode }` — `mode` is `'new'` or `'edit'`; `collection` is `undefined` while creating |
| Host form | **Yes** — form key `collection` |
#### `collection.form_sidebar`
| Where | Collection create and edit pages, end of the sidebar column |
|---|---|
| Use | Collection-scoped cards — merchandising rules, feed settings, external sync state |
| Context | `{ collection, mode }` — as for `collection.form_main` |
| Host form | **Yes** — form key `collection` |
#### `catalog.form_sidebar`
| Where | Catalog detail page (`products/catalogs/$catalogId`), end of the sidebar column |
|---|---|
| Use | B2B catalog cards — ERP contract references, approval state, export settings |
| Context | `{ catalog, canEdit }` — the `Catalog` record; `canEdit` is whether the viewer may update it |
| Host form | **Yes** — form key `catalog` |
#### `price_list.form_sidebar`
| Where | Price list create and detail pages (`products/price-lists/new`, `products/price-lists/$priceListId`), end of the sidebar column |
|---|---|
| Use | Price-list cards — sync state with an external pricing engine, audit notes |
| Context | `{ priceList, mode }` — `mode` is `'create'` or `'edit'`; `priceList` is `undefined` in create mode |
| Host form | **Yes** — form key `price_list` |
### Orders and customers
#### `order.form_main`
| Where | Order detail page (`orders/$orderId`), end of the main column |
|---|---|
| Use | Wide order cards — a shipment timeline from a carrier, a support conversation, a fraud report |
| Context | `{ order }` — the full `Order` record |
| Host form | No — widgets save via their own API calls |
#### `order.form_sidebar`
| Where | Order detail page (`orders/$orderId`), end of the sidebar column |
|---|---|
| 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_main`
| Where | Customer detail page (`customers/$customerId`), end of the main column |
|---|---|
| Use | Wide customer cards — subscriptions, reviews the customer wrote, a support history |
| Context | `{ customer }` — the full `Customer` record |
| Host form | No — the page edits through sheets; widgets save via their own API calls |
#### `customer.form_sidebar`
| Where | Customer detail page (`customers/$customerId`), end of the sidebar column |
|---|---|
| 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 |
#### `company.form_main`
| Where | Company detail page (`companies/$companyId`), end of the main column |
|---|---|
| Use | B2B account cards — credit terms, approval settings, external account references |
| Context | `{ company, kind, canEdit }` — `kind` is the company's own `kind`, `canEdit` whether the viewer may write |
| Host form | No — the widget owns its persistence |
#### `company.form_sidebar`
| Where | Company detail page, end of the sidebar column |
|---|---|
| Use | Narrow company-scoped cards alongside the main form |
| Context | `{ company, kind, canEdit }` |
| Host form | No |
#### Company membership slots
The company's member list and its "Add member" sheet carry three smaller slots, built for an extension that gives members roles.
| Slot | Where | Context |
|---|---|---|
| `company_membership.row_meta` | Under each member's email in the member list | `{ membership, companyId, canEdit }` |
| `company_membership.row_actions` | Each member's actions menu, above "Remove member" — render `<DropdownMenuItem>`s | `{ membership, companyId }` |
| `company_membership.form_fields` | The "Add member" sheet, below the email field. **Replaces** a built-in note about roles | `{ companyId, onChange }` — call `onChange(params)` and those params are merged into the request that adds the member |
### Promotions
#### `promotion.form_sidebar`
| Where | Promotion create and detail pages (`promotions/new`, `promotions/$promotionId`), end of the sidebar column |
|---|---|
| Use | Campaign attribution, budget tracking, external coupon-system sync |
| Context | `{ promotion, mode }` — `mode` is `'create'` or `'edit'`; `promotion` is `undefined` in create mode |
| Host form | **Yes** — form key `promotion` |
### Inventory
#### `purchase_order.form_main`
| Where | Purchase order detail page (`purchase-orders/$purchaseOrderId`), end of the main column |
|---|---|
| Use | Supplier correspondence, shipment tracking for inbound goods, quality-check results |
| Context | `{ purchaseOrder }` — the full `PurchaseOrder` record |
| Host form | No |
#### `purchase_order.form_sidebar`
| Where | Purchase order detail page (`purchase-orders/$purchaseOrderId`), end of the sidebar column |
|---|---|
| Use | Supplier portal links, ERP sync status, landed-cost notes |
| Context | `{ purchaseOrder }` — the full `PurchaseOrder` record |
| Host form | No |
#### `stock_transfer.form_main`
| Where | Stock transfer detail page (`transfers/$transferId`), end of the main column |
|---|---|
| Use | Carrier tracking events, packing lists from a warehouse system |
| Context | `{ transfer }` — the full `StockTransfer` record |
| Host form | No |
#### `stock_transfer.form_sidebar`
| Where | Stock transfer detail page (`transfers/$transferId`), end of the sidebar column |
|---|---|
| Use | Carrier tracking, warehouse-system sync status |
| Context | `{ transfer }` — the full `StockTransfer` record |
| Host form | No |
### Sellers (marketplace)
These slots are on the store owner's seller management pages in the admin dashboard. For the seller's own view, see the seller panel slots below.
#### `seller.form_main`
| Where | Seller detail page (`sellers/$sellerId`), end of the main column |
|---|---|
| Use | Seller-scoped cards — payout configuration, onboarding state, compliance records |
| Context | `{ seller, canEdit }` — the full `Seller` record; `canEdit` is whether the viewer may update it |
| Host form | No |
#### `seller.form_sidebar`
| Where | Seller detail page, end of the sidebar column |
|---|---|
| Use | Narrow seller-scoped cards — risk score, verification status, external account links |
| Context | `{ seller, canEdit }` |
| Host form | No |
#### `seller_payout.form_main`
| Where | Seller payout detail page (`sellers/payouts/$payoutId`), end of the main column |
|---|---|
| Use | Payout-scoped cards — remittance advice, the transfer as seen by the payment provider |
| Context | `{ payout }` — the full `SellerPayout` record |
| Host form | No |
#### `seller_payout.form_sidebar`
| Where | Seller payout detail page, end of the sidebar column |
|---|---|
| Use | Accounting-system sync status, links to the provider's dashboard |
| Context | `{ payout }` |
| Host form | No |
### Settings
#### `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` |
#### `delivery_profile.form_main`
| Where | Delivery profile page (`settings/delivery-profiles/$profileId`), below the zones and methods |
|---|---|
| Use | Rate tables from a carrier, a preview of what checkout offers for the profile |
| Context | `{ deliveryProfile }` — the full `DeliveryProfile` record |
| Host form | No — the page edits through sheets; widgets save via their own API calls |
#### `delivery_profile.form_sidebar`
| Where | Delivery profile page, end of the sidebar column |
|---|---|
| Use | Carrier account status, a sync state from a fulfillment system |
| Context | `{ deliveryProfile }` — the full `DeliveryProfile` record |
| Host form | No |
#### `webhook_endpoint.form_sidebar`
| Where | Webhook endpoint detail page (`settings/webhooks/$webhookEndpointId`), end of the sidebar column |
|---|---|
| Use | Notes on the receiving system, links to its logs, a "send test event" action |
| Context | `{ endpoint }` — the full `WebhookEndpoint` record |
| Host form | No |
## Sheet slots
The create and edit sheets of the resources below render a slot after their built-in fields. Each sheet is a host form: a widget binds inputs with `useHostForm()`, registers them under the form key (the slot's prefix), and they save with the sheet's own Create or Save button. The matching Admin API endpoint accepts what the model's `additional_permitted_attributes` declares (see [Adding an Attribute to a Core Resource](/developer/customization/api#adding-an-attribute-to-a-core-resource)).
Every sheet passes `mode` — `'new'` or `'edit'` — and its record, which is `undefined` while creating.
| Slot | Where | Context |
|---|---|---|
| `market.form_fields` | Settings → Markets | `{ market, mode }` |
| `stock_location.form_fields` | Settings → Stock locations | `{ stockLocation, mode }` |
| `tax_rate.form_fields` | Settings → Taxes → Rates | `{ taxRate, mode }` |
| `tax_category.form_fields` | Settings → Taxes → Categories | `{ taxCategory, mode }` |
| `channel.form_fields` | Settings → Sales channels | `{ channel, mode }` |
| `policy.form_fields` | Settings → Policies | `{ policy, mode }` |
| `package_type.form_fields` | Settings → Package types | `{ packageType, mode }` |
| `product_type.form_fields` | Settings → Product types | `{ productType, mode }` |
| `delivery_zone.form_fields` | A delivery profile's zone sheet | `{ deliveryZone, deliveryProfileId, mode }` |
| `delivery_method.form_fields` | A delivery profile's method sheet | `{ deliveryMethod, deliveryProfile, mode }` |
| `option_type.form_fields` | Products → Options | `{ optionType, mode }` |
| `customer_group.form_fields` | Customers → Groups | `{ customerGroup, mode }` |
Staff invitations have no slot: the invitations endpoint deliberately accepts no extension attributes, because what it takes decides who gets access.
## Seller panel slots
Rendered by the marketplace seller panel (`@spree/seller-dashboard`) rather than the admin dashboard, and registered the same way, in the seller panel's own plugins. Their names start with `seller.` followed by the page — `seller.form_main` and `seller.form_sidebar` above belong to the admin dashboard instead.
The product page is a host form with the form key `seller.product` (`seller.product.media` and `seller.product.variant` for the rows its sheets edit): fields a widget binds with `useHostForm()` save with the product. The Seller API accepts only the attributes your extension declares in `additional_seller_permitted_attributes` — see [Writable by sellers](/developer/customization/api#writable-by-sellers). The other seller panel pages have no page-wide form, so widgets there save via their own Seller API calls.
| Slot | Where | Context |
|---|---|---|
| `seller.product.form_main` | Product create and edit pages, end of the main column | `{ product, mode }` — `mode` is `'new'` or `'edit'`; `product` is `undefined` while creating |
| `seller.product.form_sidebar` | Product create and edit pages, end of the sidebar column | `{ product, mode }` — `mode` is `'new'` or `'edit'`; `product` is `undefined` while creating |
| `seller.product.media.form_fields` | The media editor sheet on the product pages | `{ productId, media, mediaIndex, fieldPrefix }` — host form key `seller.product.media` |
| `seller.product.media.actions` | The product pages' Media card, after the "Add video link" button | `{ productId, addMedia }` — see [`product.media.actions`](#product-media-actions) |
| `seller.product.variant.form_fields` | The variant editor sheet on the product pages | `{ variant, variantIndex, fieldPrefix }` — host form key `seller.product.variant` |
| `seller.order.form_sidebar` | Order detail page, end of the sidebar column | `{ order }` |
| `seller.payout.form_sidebar` | Payout detail page, end of the sidebar column | `{ payout }` |
| `seller.profile.form_main` | Profile page, end of the main column | `{ profile }` |
| `seller.profile.form_sidebar` | Profile page, end of the sidebar column | `{ profile }` |
| `seller.stock_location.form_fields` | Stock location create and edit sheets | `{ stockLocation, mode }` — host form key `seller.stock_location` |
| `seller.package_type.form_fields` | Package type create and edit sheets | `{ packageType, mode }` — host form key `seller.package_type` |
| `seller.team.actions` | Team page, in the header's action area — bulk invite, export, an external directory sync | `{ sellerId }` |
| `seller.team.after` | Team page, below the member list — audit log, role explainer, seat usage | `{ sellerId }` |
## Sign-in slots
### `login.after`
| Where | Login page, below the sign-in options |
|---|---|
| Use | Extra content for people who can't sign in yet — a link to a sign-up page, a support contact, terms of service |
| Context | none |
Nobody is signed in when this renders, so only call endpoints that need no session. Links to a [public page](/developer/dashboard/customization/routes#pages-outside-a-store) fit here.
## Replaceable slots
These slots render built-in content when nothing is registered. Registering a component **replaces** that content rather than adding to it.
### `store_selection`
| Where | The page a signed-in user lands on at `/`, before entering a store. By default it opens their first store, or shows `no_store_access` when they have none |
|---|---|
| Use | Replace the whole page — for example, with a list of stores to choose from and a link to an onboarding page that creates one |
| Context | `{ user, signOut }` — `user` is the signed-in admin, with the stores they can open in `user.stores`; `signOut()` ends the session |
Import the name as `STORE_SELECTION_SLOT` from `@spree/dashboard-core` rather than typing it. Every sign-in, password reset and accepted invitation lands here, so the replacement owns both cases the default handles: a user with stores (link to `/$storeId`, or open one straight away with `<Navigate>`) and a user with none. The page renders on a blank canvas; wrap it in `AuthShell` from `@spree/dashboard/components/spree/auth-shell` to match the login page.
### `no_store_access`
| Where | The screen shown to a signed-in admin who has a role on no store |
|---|---|
| Use | Replace the built-in "no access" message — for example, with a request-access form or a link to your own onboarding |
| Context | `{ user, signOut }` — `user` is the signed-in admin; `signOut()` ends the session |
Import the name as `NO_STORE_ACCESS_SLOT` from `@spree/dashboard-core` rather than typing it.
### `getting-started.task.<name>`
| Where | The body of one step on the Getting Started checklist (`getting-started`) |
|---|---|
| Use | Replace a step's description and link with your own flow — or give a setup task your extension added on the backend its own UI |
| Context | `{ task, store, storeId }` — `task` is the `SetupTask` record (`name`, `done`, …) |
`<name>` is the task's `name` as the API returns it.
## Editor slots (dynamic)
Promotions, price lists, and payment methods each pick their editor by type. The slot names are computed from the type's `api_type` shorthand, so registering against the right name is what hooks your editor in. The promotion and price list editor slots **replace** the built-in editor, which is generated from the type's preference schema.
### `promotion.rule_form.<type>`
| Where | The sheet that edits one promotion rule (e.g. `promotion.rule_form.product`) |
|---|---|
| Use | A custom editor for a rule whose settings don't fit the generated form |
| Context | `{ draft, onSave, onClose }` — edit `draft` locally and call `onSave(next)`; the promotion saves everything when the merchant clicks Save |
### `promotion.action_form.<type>`
| Where | The sheet that edits one promotion action (e.g. `promotion.action_form.free_shipping`) |
|---|---|
| Use | A custom editor for an action — calculators, line-item pickers |
| Context | `{ draft, onSave, onClose }` — same as rules |
### `price_list.rule_form.<type>`
| Where | The sheet that edits one price list rule (e.g. `price_list.rule_form.volume_rule`) |
|---|---|
| Use | A custom editor for a price rule |
| Context | `{ draft, onSave, onClose }` — same as promotion rules |
### Payment method editor slots
Used by `<PaymentMethodForm>` to let payment-provider plugins replace pieces of the editor sheet. The slot names are computed per provider type (`stripe`, `bogus`, …), so registering against the right name is what hooks your editor in.
#### `payment_method.guide.<providerType>`
| Where | Above the preferences form |
|---|---|
| Use | Banner explaining what the integration does, what credentials to use, links to provider docs |
| Context | `PaymentMethodEditorContext` (see below) |
#### `payment_method.form.<providerType>`
| Where | In place of the auto-generated preferences form |
|---|---|
| Use | Render a custom React form when the provider's preferences are too complex for the generated UI (multi-step OAuth, environment switchers, …) |
| Context | `PaymentMethodEditorContext` |
#### `payment_method.actions.<providerType>`
| Where | Sheet footer, before Save/Cancel |
|---|---|
| Use | Provider-specific action buttons — "Test connection", "Rotate keys", "Open dashboard in provider" |
| Context | `PaymentMethodEditorContext` |
#### `PaymentMethodEditorContext`
```ts
interface PaymentMethodEditorContext {
mode: 'create' | 'edit'
type: string // STI shorthand (`stripe`, `bogus`, …)
paymentMethod: PaymentMethod | null // null in create mode
preferenceSchema: PreferenceField[]
preferences: Record<string, unknown>
onPreferencesChange: (next: Record<string, unknown>) => void
form: UseFormReturn<PaymentMethodFormValues> // RHF instance for top-level fields
}
```
Helpers for building the slot name:
```ts
import {
paymentMethodGuideSlot,
paymentMethodFormSlot,
paymentMethodActionsSlot,
} from '@spree/dashboard/components/spree/payment-method-editors/types'
paymentMethodFormSlot('stripe') // → "payment_method.form.stripe"
```
Use these instead of constructing the string yourself, so a rename in one place doesn't silently break your registration.
## Adding a new slot
If a built-in page should expose a new injection point:
1. Pick a name (`<resource>.<area>`, e.g., `order.timeline`; `seller.<page>.<area>` in the seller panel)
2. Add `<Slot name="..." context={{ resource: order, /* ... */ }} />` at the call site
3. If the slot sits inside the page's form, make it a host form: wrap the form in `<FormProvider>`, hydrate with `extensionFormValues('<resource>', record)`, and merge `extensionSubmitValues('<resource>', form)` into the save payload — the collection page is the reference
4. Document the slot here — host, intent, context shape, and form key
5. Open the PR
The slot is not "live" until the docs land — without an entry here, no plugin author knows it exists.
## Reference
- [`<Slot>` source](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/components/slot.tsx)
- [`slot-registry`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/slot-registry.ts) — `registerSlot`, `removeSlot`, `updateSlot`, `useSlotEntries`
- [Slots customization page](/developer/dashboard/customization/slots) — how to register against a slot