Wix Dashboard Page Builder
Dashboard pages appear in the site owner's Wix dashboard, where admins manage data and configure settings.
Plan the Workflow Before the Components
A dashboard page is a workflow, not a screen. The site owner has to understand the situation, focus on what needs attention, investigate one record, act, and see the result confirmed — so translate the prompt into those needs before choosing any component.
Do this first because a bare filtered table answers "what are all the records" and neither "which one needs my attention" nor "why did this happen" — and a table is what you get by default if the workflow was never named. Read UX Success Model now, and run its evaluation checklist before calling the page done. Which component serves each need is the installed package's own answer — see The Discovery Chain.
UI Libraries — Read Before Writing Any JSX
@wix/patterns first, @wix/design-system for the leaf UI inside its shell, custom React only when neither has it. Do not hand-write React for anything either library provides, and do not decide a component is missing without checking.
The order, what each library owns, and how to look a name up are stated once: SKILL.md → Component Selection Order.
Theme: the page's iframe inherits none of the Business Manager redesign. Wrap the entry file in the app's BusinessManagerTheme, import icons from @wix/wix-ui-icons-common/lazy, and style with --wds-* tokens or skin/size props — BUSINESS_MANAGER_THEME.md, BUSINESS_MANAGER_TOKENS.md.
Scaffold
Use wix generate --params with all required fields:
wix generate --params '{"extensionType":"DASHBOARD_PAGE","title":"<title>","route":"<route>"}'| Field | Constraint |
|---|---|
title |
Display name shown in the dashboard sidebar. |
route |
URL path segment (lowercase alphanumeric + hyphens). The page is served at /dashboard/<route>. The scaffold param is route; the builder file's runtime field is routePath. |
The CLI generates the folder, the page's component file (<page>.tsx, the builder's component), the builder file, the UUID and the src/extensions.ts registration.
After scaffolding, check routePath: use support-tickets, not /support-tickets; a leading slash fails registration even if the build passes. Internal router paths stay /, /:id, /new, never prefixed with <route> — see <pkgRoot>/dist/docs/Collection to Entity Flow.md.
Before writing that UI: copy in the installed @wix/patterns page template that matches, per DRAFT_TEMPLATE.md — don't compose the shell from scratch.
Then, for whatever the template doesn't cover: probe <pkgRoot>/dist/docs/index.json once with grep/python3 — never a whole-file Read, which truncates silently (Prerequisites). Its importPath, examples and bundle decide whether you open anything else. Each Bash call is a fresh shell — re-set the path variable every time.
Capabilities
A dashboard page runs as the Wix user — see Identity and Elevation Requirement before deciding where an SDK call runs.
Data Operations (Wix Data SDK)
See Wix Data Reference.
- Read:
items.query('Collection').filter/sort.limit.find()→{ items, totalCount, hasNext } - Write:
items.insert | update | remove. Ensure collection permissions allow the action
Query methods: eq, ne, gt, ge, lt, le, between, contains, startsWith, endsWith, hasSome, hasAll, isEmpty, isNotEmpty, and, or, not, ascending, descending, limit, skip, include
Dashboard APIs
See Dashboard API Reference for all methods, page IDs, and examples.
Key methods, all on the dashboard object from @wix/dashboard (signatures, page IDs, and examples in the reference above):
- Navigation:
navigate(),navigateBack(),getPageUrl() - Feedback and chrome:
showToast(),setPageTitle() - Overlays:
openModal()(see Dashboard Modal reference),openMediaManager() - State and lifecycle:
observeState(),onBeforeUnload(),onLayerStateChange() - Slots:
addSitePlugin()
CRITICAL: Using Modals in Dashboard Pages
Dashboard Pages cannot use <Modal />. For a true dialog overlay you MUST use a dashboard modal extension — never a React modal or the WDS Modal component. Reserve it for dialogs that neither write nor display a listed record (delete/discard confirmations, unsaved-changes prompts, notices), plus any dialog on a page that lists nothing (settings, config). They open via dashboard.openModal() — see Dashboard Modal reference.
🛑 The test — does the dialog create, update, or display one record this page lists? If yes, it is an
EntityPage, not a modal — whether those records come from a CMS collection or an existing Wix app's SDK. A create / "add new" form is included: it writes the record, so it is anEntityPageeven though nothing is being edited yet. "It's a simple data-entry dialog, not an entity edit" is the wrong reading — the most common way the patterns-first rule gets dropped after the table is already correct.The
EntityPagecomes from@wix/patterns, reached viausePatternsNavigate().navigateToEntityPage, withuseEntityPageowning fetch/save/validation and@wix/patterns/formowning form state. Its route is registered withPatternsReactRouteinsidePatternsReactRouter— so do not hand-roll page location state to fake a second view (useState<PageLocation>as a stand-in for a route); that is the router's job, and needing it is the signal you skipped one.That's not a rule against
withDashboard: the router requires it above itself and alocationprop, which the page gets fromdashboard.observeState(a Wix CLI app passes no props to dashboard pages). Skip it andPatternsReactRouterthrows at open, though typecheck, bundling, andwix previewall pass. Read<pkgRoot>/dist/docs/withDashboard.md(ships from 1.465.0; on older installs,PatternsReactRouter.md's Requirements).If this page lists nothing (settings, config) the rule doesn't apply. But "I built the list without
@wix/patterns" is not an exception: a page that lists records should be aCollectionPage.See Entity create and edit and WIX_PATTERNS_DOCS.md; for the
useEntityPagecall itself,<pkgRoot>/dist/docs/useEntityPage.md.
Ecom Navigation: See Ecom Navigation Reference for ecom-specific navigation helpers.
Embedded Script Configuration API
When building a dashboard page to configure an embedded script, see Dynamic Parameters Reference.
Key points:
- Use
embeddedScriptsfrom@wix/app-management - Parameters cross the API as strings in both directions — convert on load, and convert booleans/numbers back to strings on save
- Use the
withProviderswrapper when dynamic parameters are present
Examples
Each starts from one of the package's page templates, found through DRAFT_TEMPLATE.md — copy its files, then adapt. Only what differs per request is listed below; the wiring lives solely in the template.
| Request | Template | Adapt |
|---|---|---|
| "Dashboard page to manage blog posts" | Collection and Entity | Columns for the post fields named; search, row actions and empty state from the collection's own APIs; add/edit navigate to the EntityPage; {feature}-api.ts calls @wix/blog |
| "Settings page for notification preferences" | Settings Page | SettingsPage shell with a WDS field per preference (FormField, Input, ToggleSwitch); save confirms with dashboard.showToast(), and dashboard.onBeforeUnload() warns on unsaved changes — no collection, no table hook, no router |
| "Admin panel for customer orders" | Collection and Entity | Filters, sorting and row actions from the collection APIs — not a hand-built WDS filter bar; status Badge is leaf UI in a cell; data source is @wix/ecom, never CMS (see SDK-First Rule); viewing or editing opens the EntityPage, and a Dashboard Modal appears only for the delete confirmation (see Entity create and edit) |
| "Settings page for the coupon popup embedded script" | Settings Page | Fields for headline, coupon code, min cart value, enable toggle; swap fetch/onSave for embeddedScripts.getEmbeddedScript()/embedScript(), string-converted both ways (see Dynamic Parameters); use withProviders in place of the template's plain provider |
| "Admin page to manage fees, with an app settings section" | Collection and Entity, plus the Settings Page's settings page as one more route | One extension, not several — fee fields/calls into every route component. Skipping the router's location plumbing here passes tsc/wix build silently and fails only in a browser |
API Spec Support
When an API specification is provided, you can call those endpoints — see API Spec Reference.
Layout Guidelines
Content layout inside the page shell — the 6px base unit, the 12-column grid, spacing tokens, form/display/marketing/wizard layouts: see WDS Layout Reference.
Remember the split: @wix/patterns owns the shell and anything collection-shaped; that reference covers only content placed inside.