Skip to content
Cratis

Getting started

You’ve built an Arc backend—a RegisterAuthor command and an AllAuthors query—and dotnet build generated typed proxies for both. Components connects those proxies to typed forms, dialogs, and data views with documented command, validation, and query-lifecycle behavior.

Prerequisites

Section titled “Prerequisites”
  • A React 19 application.
  • An Arc frontend connected through generated proxies. The Arc frontend guide sets this up.

Install and wire it up

Section titled “Install and wire it up”

  1. Install Components.

    Install Components 4
    npm install @cratis/components@^4

    React Aria, the internationalized date implementation, and React Icons are internal dependencies. The current package manifest does not declare a separate UI kit or theme runtime, and consumers do not configure an icon-package peer.

    The package declares React, Arc, Fundamentals, reflect-metadata, and tsyringe peer ranges. Its Arc range is >=20.3.1 <23; keep @cratis/arc and @cratis/arc.react on the same version used by the application’s generated proxies. A strict installer can use this explicit form (replace the example Arc version when needed):

    Install explicit peers
    ARC_VERSION=22.6.2
    npm install @cratis/components@^4 \
      "@cratis/arc@$ARC_VERSION" "@cratis/arc.react@$ARC_VERSION" \
      @cratis/fundamentals@^7.10.3 react@^19 react-dom@^19 \
      reflect-metadata@0.2.2 tsyringe@4.10.0

    pixi.js@^8.20.0 is an additional optional peer, needed only if you use Canvas or PivotViewer. Every other component needs nothing beyond the peers above; install Pixi later, when you reach a spatial workspace or card-grid screen. See Choosing a component.

  2. Import the Cratis-owned stylesheets once, at your application entry point:

    main.tsx
    import '@cratis/components/tokens';
    import '@cratis/components/styles';
    import '@cratis/components/theme'; // optional baseline appearance

    tokens defines stable --cratis-* variables with conservative light defaults. styles supplies no-Preflight component structure in low-priority Cratis layers. theme adds automatic/explicit dark mode, forced colors, and themed subtrees.

    A product with its own design system can omit theme, map its own variables onto --cratis-*, and customize stable data-cratis-part elements or pt attributes.

  3. Mount the provider around your application:

    App.tsx
    import { CratisComponentsProvider } from '@cratis/components';
    

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

Yarn PnP with Arc React 22.6.2

Section titled “Yarn PnP with Arc React 22.6.2”

The current @cratis/arc.react@22.6.2 package imports rxjs without declaring it. A strict Yarn PnP consumer must install rxjs@7.8.2 and temporarily add this package extension until Arc publishes corrected metadata:

.yarnrc.yml
packageExtensions:
    '@cratis/arc.react@22.6.2':
        dependencies:
            rxjs: '7.8.2'

What the provider sets up

Section titled “What the provider sets up”

The provider supplies the locale, Components-specific labels, and an optional app-wide toast region. React Aria uses the locale for date, number, keyboard, and screen-reader behavior. Styling remains CSS-owned rather than provider-owned.

generated proxy

RegisterAuthor · AllAuthors
Components

CommandDialog · DataTable
Cratis-owned semantic markup
React Aria behavior
--cratis-* tokens

React Aria is an implementation dependency. Public props, parts, CSS variables, and event types are owned by Cratis.

Localize Components labels

Section titled “Localize Components labels”

React Aria supplies its own locale data. Configure only labels owned by Components:

<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',
            },
        },
    }}
>
    <YourApp />
</CratisComponentsProvider>

See the payoff

Section titled “See the payoff”

CommandDialog takes the generated command, renders its fields and actions, and disables confirmation while execution is in progress:

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


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

No isExecuting state, action wiring, or duplicate validation logic is required. If the C# command changes, the generated proxy makes this component fail compilation until it is updated.

Choose how it looks

Section titled “Choose how it looks”

Choose one styling posture:

  • Import theme for the Cratis baseline.
  • Define your own --cratis-* token values for a product design system.
  • Add classes or ordinary HTML attributes through each component’s Cratis-owned pt parts.
  • Target stable data-cratis-part and state attributes when product CSS needs structural control.

Do not target React Aria class names or internal DOM structure. See Styling and Stable component parts.

Recap

Section titled “Recap”

You installed one UI package, imported Components-owned styles, and mounted a locale/toast provider. Components owns the public React contract, Arc supplies command and query behavior, and React Aria supplies selected low-level interaction primitives internally.

Where to go next

Section titled “Where to go next”