@cratis/components

The React UI component of Cratis Platform, published as @cratis/components: command dialogs, typed forms, query-backed tables, and application surfaces composed around Cratis Arc. Chronicle is not required.

The package provides React components for Arc commands, queries, dialogs, forms, and application surfaces. Components owns its public markup, TypeScript contracts, stable parts, and design tokens. React Aria supplies selected interaction primitives internally; consumers do not import or style React Aria.

• Canonical Components documentation
• Renderer adapters and coexistence
• Migration guide
• Private security reporting

Choose your first surface

• A generated command or query: follow Getting started for peers, CSS, and both providers. Then build the library screen against the linked Arc backend and generated proxies. Components does not supply those contracts.
• Already-loaded rows or local UI state: choose DataTableCore or a controlled control from the decision guide. That surface need not call an Arc backend; the required Arc package peers below do not become optional.
• An existing Components 3 application: use the migration guide before copying Components 4 imports into it.

The tutorial continues from a table to an add-author dialog and a selected author's books. A command's success closes its dialog; a row appears when the query delivers updated data. For failures, start with the symptom guide.

Install

npm install @cratis/components@^4

The current package manifest declares these peer dependencies:

• @cratis/arc and @cratis/arc.react >=20.3.1 <23
• @cratis/fundamentals ^7.10.3
• optional pixi.js ^8.20.0
• react and react-dom ^19.0.0
• reflect-metadata 0.2.2
• optional tsyringe 4.10.0 (Arc React installs it as its own dependency)

Strict installers can declare them explicitly; keep both Arc packages on the version your generated proxies were produced with. This checkout pins its Arc development dependencies to 22.156.2; use the version matching your generated proxies:

ARC_VERSION=22.156.2
npm install @cratis/components@^4 \
  "@cratis/arc@$ARC_VERSION" "@cratis/arc.react@$ARC_VERSION" \
  @cratis/fundamentals@^7.19.2 react@^19 react-dom@^19 \
  [email protected]

The current manifest does not declare PrimeReact, PrimeIcons, or PrimeUI packages as dependencies or peers. Applications retaining direct dependencies keep their own package, provider, styling, and license boundaries.

The generated compatibility schema v2 contract is published at @cratis/components/compat-manifest.json. It records the supported Components and tooling windows, the authorized seven-package scope, shared release version, renderer ABI/profile ranges, and exact lower/current adapter evidence. release.md at the repository root describes the label-driven publication policy.

Renderer-adapter authors can import the public draft 2020-12 metadata schema from @cratis/components/schemas/ui-adapter.schema.json. It validates the static package.json#cratis object; runtime behavior still requires @cratis/components.conformance. See the renderer-adapter documentation for the boundary and limitations.

Yarn PnP note: @cratis/[email protected] imports rxjs without declaring it. Strict PnP consumers that stay on that version install [email protected] and add a packageExtensions entry for @cratis/[email protected]; Arc React 22.16.0 does not need it. The canonical getting-started guide contains the exact YAML.

pixi.js@^8.20.0 is an additional optional peer, required only by Canvas and PivotViewer (the Spatial capability profile — see Import from explicit subpaths below). Every other subpath needs nothing beyond the peers above:

npm install pixi.js@^8.20.0

Keep exactly one compatible Pixi resolution across the application and Components; two installed copies produce nominal TypeScript incompatibilities for PIXI.Container and pointer-event types even when both satisfy ^8.20.0. The capability-subpath table below identifies the current Pixi-dependent surfaces.

Styles

/* index.css */
@import '@cratis/components/tokens';
@import '@cratis/components/styles';
@import '@cratis/components/theme'; /* optional baseline appearance */

Import this file once at the application entry point, for example import './index.css';. Import the stylesheets from CSS rather than from TypeScript: the subpaths ship no type declarations, so on TypeScript 6, which checks side-effect imports by default, import '@cratis/components/tokens' in a .tsx file fails with TS2882. A Vite project type-checks import './index.css' through its vite/client types. A project that still imports the stylesheet subpaths from TypeScript declares them in an ambient .d.ts file:

declare module '@cratis/components/tokens';
declare module '@cratis/components/styles';
declare module '@cratis/components/styles/base';
declare module '@cratis/components/theme';

tokens supplies conservative light defaults. styles contains structural rules and internal utilities in low-priority Cratis cascade layers, with no Tailwind Preflight/reset or token duplication. theme adds automatic/explicit dark mode, forced colors, and themed subtrees. It also maps Arc's --color-error and --color-error-bg for each light and dark scheme, so an app that customizes those Arc tokens sets them after importing theme.

A custom product design omits theme, imports product CSS after tokens and styles, and maps its canonical values directly to --cratis-*.

styles is every component's CSS in one file. To pay only for the surfaces the application mounts, import the shared base plus one entry point per subpath instead:

@import '@cratis/components/tokens';
@import '@cratis/components/styles/base';
@import '@cratis/components/Dialogs/styles';
@import '@cratis/components/DataTables/styles';

Every JavaScript subpath publishes a matching <subpath>/styles, self-contained for that subpath. styles/base carries the internal utilities and the cascade-layer order, and is required exactly once; the aggregate already contains it.

Provider

Import reflect-metadata once at the entry point, before the styles, and mount the Components provider inside Arc's <Arc> provider. <Arc> supplies the command and query runtime used by the generated proxies; CratisComponentsProvider does not replace it:

import 'reflect-metadata';
import { Arc } from '@cratis/arc.react';
import { CratisComponentsProvider } from '@cratis/components';

export const App = () => (
    <Arc>
        <CratisComponentsProvider value={{ locale: 'en-US' }} toaster>
            <Application />
        </CratisComponentsProvider>
    </Arc>
);

The provider owns locale, Components-specific labels, optional renderer selection, and the toast region. The default renderer needs no additional package. Certified renderer packages implement the stable, nine-slot stable-presentation/v1 primitive profile; they never replace the full Components catalog. They share the Components repository release version and are selected with the provider's library prop:

• @cratis/components.mui — MUI 9.x / Emotion 11.x stable presentation slots;
• @cratis/components.primereact — PrimeReact 11.x stable presentation slots, with an application-owned outer provider and license key;
• @cratis/components.primereact10 — PrimeReact 10.9.9+ stable presentation slots, with its separate MIT-era provider, global theme, and upstream-major boundary.

Adapter-specific themes, providers, SSR setup, peers, and license boundaries remain documented by the adapter package. Styling for the built-in renderer is CSS-owned. The canonical renderer guide bounds primitive adaptation, direct vendor coexistence, custom composition, unsupported claims, and license/key ownership.

<CratisComponentsProvider
    value={{
        locale: 'nb-NO',
        messages: {
            paginator: {
                navigation: 'Sidenavigasjon',
                first: 'Første side',
                previous: 'Forrige side',
                next: 'Neste side',
                last: 'Siste side',
            },
            datePicker: {
                today: 'I dag',
                clear: 'Tøm',
                openCalendar: 'Åpne kalender',
                previousMonth: 'Forrige måned',
                nextMonth: 'Neste måned',
            },
        },
    }}
>
    <Application />
</CratisComponentsProvider>

Command forms

import { CommandDialog } from '@cratis/components/CommandDialog';
import { InputTextField } from '@cratis/components/CommandForm';
import { RegisterAuthor } from './RegisterAuthor';

export const RegisterAuthorDialog = () => (
    <CommandDialog<RegisterAuthor>
        command={RegisterAuthor}
        title='Register author'
        okLabel='Register'
    >
        <InputTextField<RegisterAuthor> value={(command) => command.name} title='Name' />
    </CommandDialog>
);

Fields bind directly to generated command properties and surface server validation through the Arc command-form context. Required command values the user does not type, such as a generated id, belong in initialValues; onBeforeExecute runs only after validation and cannot enable the confirm button.

Query-backed tables

import { Column, DataTableForObservableQuery } from '@cratis/components/DataTables';
import { ObserveAuthors } from './ObserveAuthors';

<DataTableForObservableQuery
    query={ObserveAuthors}
    dataKey='id'
    emptyMessage='No authors'
>
    <Column field='name' header='Name' sortable filter />
    <Column field='email' header='Email' filter />
</DataTableForObservableQuery>;

Arc owns server paging. Client filters apply only to the loaded page; complete-result filtering belongs in query arguments and runs on the server before paging.

Notifications

import { Toaster, toast } from '@cratis/components/Notifications';

<Toaster position='top-right' />;

toast.success({
    title: 'Saved',
    description: 'Your changes were saved.',
});

The queue, promise lifecycle, timers, dispatch substitution, toast frame, and region are Components-owned implementation surfaces.

Custom styling

Documented customizable component parts use stable data-cratis-part names. Components with per-instance customization expose a typed pt object containing ordinary HTML attributes for their documented parts.

import { Dialog } from '@cratis/components/Dialogs';

<Dialog
    title='Edit account'
    pt={{
        backdrop: { className: 'product-dialog-backdrop' },
        root: { className: 'product-dialog' },
        content: { className: 'product-dialog-content' },
    }}
>
    Content
</Dialog>;

:root {
    --cratis-primary-color: var(--product-accent);
    --cratis-action-background: var(--product-action);
    --cratis-action-background-hover: var(--product-action-hover);
    --cratis-action-background-active: var(--product-action-active);
    --cratis-action-text: var(--product-on-action);
    --cratis-surface-card: var(--product-surface);
    --cratis-surface-overlay: var(--product-surface-raised);
    --cratis-surface-border: var(--product-border);
    --cratis-control-background: var(--product-control);
    --cratis-control-border: var(--product-control-border);
    --cratis-text-color: var(--product-text);
    --cratis-focus-ring: var(--product-focus-ring);
}

.product-dialog[data-cratis-part='root'] {
    border-radius: 1rem;
}

Do not target React Aria classes or internal DOM structure.

Import from explicit subpaths

The canonical rule: the package root is setup-only; every component ships from its own subpath. Import CratisComponentsProvider, useCratisComponentsConfig, cratisDefaults, and mergeCratisComponentsConfig from the root; import every component from the subpath in its capability profile:

Foundation, Advanced React, and Spatial describe dependency and usage boundaries, not stability, maturity, accessibility, support, or quality tiers. Spatial identifies the subpaths that require the optional Pixi peer.

Components 4 removes component-family namespaces from the root. The root is setup-only so importing the provider does not traverse optional or unrelated component graphs. MIGRATION.md contains the current namespace-to-subpath mapping and migration command for existing root imports.

Components 3 migration

The current package manifest does not declare PrimeReact as a required runtime or peer. Follow the Components 3 to 4 migration guide for dependency removal, provider changes, product token mapping, stable part names, DatePicker changes, table behavior, notifications, direct Prime import replacements, the bounded Components 4 @cratis/components.migrator commands, and the @cratis/eslint-plugin-components guard. The optional Migrator is a development CLI used only while upgrading application source; its syntax-aware transforms validate the bundled compatibility manifest and installed Components support window before scanning. @cratis/components.conformance is a separate development test harness for renderer adapter authors and is not an application runtime dependency.

The old @cratis/components/styled, styledMode, CratisPreset, and primeReactStyles renderer exports are removed. Move styling to tokens and stable parts before upgrading.

License

The package metadata declares MIT for @cratis/components. Dependencies and bundled assets retain their own terms. Review the packaged LICENSE, THIRD_PARTY_NOTICES.md, and included font-license files for the exact package version you use.