Choosing a component

Several Components solve similar-looking problems, and it’s not always obvious which one to reach for. This page is the decision guide: pick by what you’re building, then follow the link to the recipe or reference.

Collecting input

The question is whether confirming the form runs a command, and whether it’s one step or several.

You want to…	Use	Why
Collect a few fields and run one command	CommandDialog	Instantiates, validates, and executes the command; handles the footer and button states. The default.
Run a command through named steps in a modal	StepperCommandDialog	A wizard over a single command — validate per step, navigate back and forth, execute at the end.
Run a command through named steps inline on the page	CommandStepper	The inline command wizard for a panel, route, or page region; it executes on the final step.
Embed command fields in a page, not a dialog	CommandForm	The same typed fields CommandDialog uses, without the dialog chrome.
Collect data and return it without running a command	Dialog	A confirmation or data-entry dialog that hands values back to the caller. No command involved.
Edit ordinary local React state	Common basic controls	Native text and choice controls expose semantic values without binding an Arc command.
Select one or more values in ordinary local React state	Dropdown	Binds a value or array to local options without binding an Arc command.

Rule of thumb: if confirming the dialog executes a generated command, it’s a CommandDialog (or its stepper variant). If it just gathers values and returns them, it’s a Dialog. Never reach for an application-owned modal — these wrappers handle validation timing, loading state, focus, and footers consistently.

Displaying data

Both render a query or observable query; the question is whether you want a whole page or a table to drop into one.

You want to…	Use	Why
A full screen: a list, a toolbar of actions, detail panels	DataPage	A resizable page composition with toolbar and detail areas wired to the query.
A table over an Arc query or observable query	DataTables	Query wrappers with server paging and loaded-page rendering.
A semantic table over an already-loaded array	DataTableCore	Local rows, single selection, loaded-page filtering/sorting, scrolling, and stable parts.
Grouping, row expansion, or controlled lazy/server sorting	Product-owned/retained table adapter	Components does not claim these advanced state contracts; keep the existing adapter deliberately.

If you’re building a list-screen-with-actions from scratch, start with the list screen recipe, which composes DataPage with CommandDialog actions.

Selection, status, and feedback

You want to…	Use	Why
Select one or more values from local options	Dropdown	Supports single, filtered, and multiple selection through a controlled value.
Show status, counts, people, progress, or loading	Display	Provides tags, badges, chips, avatars, messages, progress indicators, and skeletons.
Send an app-wide transient notification	Notifications	Provides one shared toast queue, an imperative API, and an optional app-wide toaster.

Filtering

Choose the filtering surface by where its state belongs:

You want to…	Use	Why
Filter individual table columns	Column filters	A column can use the built-in ColumnFilterMenu; the menu keeps draft changes until Apply.
Search configured fields in a DataPage	DataPage.globalFilterFields	Adds global search over the rows in the currently loaded query page.
Present option, numeric-range, or custom filter groups	FilterPanel	Supplies a standalone faceted panel while the host owns how its filter state applies to the data view.

Table column and DataPage global filters operate on the currently loaded query page. Filtering the complete result set belongs in query arguments and server logic before paging; see DataPage filtering scope.

Actions and tool palettes

Use ActionMenubar or an ordinary product action row for flat page commands. DataPage’s built-in toolbar already renders ActionMenubar, not Toolbar — that is the default action row for a page, not a canvas tool palette. Use Toolbar only for a genuine canvas/tool-palette interaction with active tools, groups, slots, folders, and fan-out panels. It is not a one-for-one replacement for a generic Prime Toolbar, and it is not a page-level action row wearing a different name.

Structured data, history, and conversation

You want to…	Use	Why
Explore or edit an object through a JSON Schema	ObjectContentEditor	Renders schema-aware properties and navigation through nested objects and arrays.
Create or edit a supported JSON Schema	SchemaEditor	Edits properties, supported types, and formats in a validated table interface.
Add controlled breadcrumbs to hierarchical data	ObjectNavigationalBar	Renders a host-owned navigation path with breadcrumb and back actions.
Explore supplied versions, events, and state changes	TimeMachine	Provides an interactive timeline while the host supplies the version data.
Build topic-based conversations from host-owned data	Chat	Provides topic, conversation, mention, emoji, and message-action surfaces with callback outputs.

Spatial workspaces

Use Canvas for a pan/zoom workspace containing positioned DOM or Pixi items, optional minimap/controls, notes, regions, or collaborative chat shapes, or PivotViewer for a faceted, zoomable card grid over a large dataset. Both belong to the Spatial capability profile and install the optional pixi.js peer — see UI foundation: Optional Pixi, clean no-Pixi core. Spatial ships at the same version and quality bar as every other component; the profile label describes what it is for and what it costs to adopt, not a lower support tier.

Canvas and PivotViewer own interaction and rendering primitives; the application owns persistence and behavior. Arc can provide commands, queries, validation, authorization, and generated bindings on its own. Applications using Arc plus Chronicle can additionally project event streams into read models — neither component has a direct Chronicle dependency; see the UI foundation capability matrix.

Putting it together

A typical CRUD screen combines these: a DataPage lists the rows, a toolbar button opens a CommandDialog to add one, and selecting a row opens another CommandDialog to edit it. That whole screen is the list screen with actions recipe.

Components does not ship every toolkit widget. Tabs, general-purpose sidebars, knobs, select-button groups, general popovers, grouped or expandable tables, controlled lazy/server table sorting, and specialized locale-aware inputs remain product-owned or in a separately configured UI toolkit. See Coming from PrimeReact for the current replacement boundaries.

Still deciding how to style any of this? See Styling.