Entry points

Custom dashboard code imports from two entry points:

• alinea/components: generic UI building blocks, such as buttons, inputs, dialogs and tables. They don't know about your content and work anywhere inside the dashboard.

• alinea/cms: what is tied to the CMS, such as the hooks that read and write field values, the entry being edited and the signed-in user, FieldChrome and the prop types of field, type and root views. See the alinea/cms API in Custom fields.

Usage

import {type FieldViewProps, useField, useFieldOptions} from 'alinea/cms'
import {Select, SelectItem} from 'alinea/components'
import type {Priority, PriorityField} from './Priority'

export function PriorityView({field}: FieldViewProps<PriorityField>) {
  const [value, setValue] = useField(field)
  const options = useFieldOptions(field)
  return (
    <Select
      label={options.label}
      value={value}
      onValueChange={next => setValue((next ?? 'normal') as Priority)}
      readOnly={options.readOnly}
    >
      <SelectItem value="low">Low</SelectItem>
      <SelectItem value="normal">Normal</SelectItem>
      <SelectItem value="high">High</SelectItem>
    </Select>
  )
}

The components are styled by the dashboard's stylesheet and theme. They are meant for code that runs inside the dashboard, but work on other pages too (see Theme tokens below).

Conventions

The API follows shadcn/ui and Radix, so the names will feel familiar:

• Compound components are named after their parts: Dialog, DialogTrigger, DialogContent, DialogTitle.

• Controlled and uncontrolled state use the same prop names everywhere: value, defaultValue and onValueChange; checked and onCheckedChange; open, defaultOpen and onOpenChange.

• Form controls take label, description, error, required, disabled, readOnly, icon and shared, and render their label and messages with Field.

• Dates and times are ISO strings (2026-09-23, 14:30). Collection keys are strings or numbers, and a selection is a Set of keys or 'all'.

• Every component accepts className and style. Each rendered part has a data-slot attribute (data-slot="dialog-content"), and variants are exposed as data-variant and data-size, which gives your CSS stable hooks.

• Colors, fonts and radii come from CSS variables such as --alinea-fg, --alinea-bg, --alinea-border, --alinea-primary and --alinea-radius. Use them in your own styles to follow the theme.

The props of every component are typed, so your editor shows what each one accepts. Types shared between components, such as Selection, Key and IconType, are exported as types from alinea/components too.

Icons

Components with an icon prop take an icon component (any component that renders an <svg>, such as those from react-icons or copied from Icones) or an element. The icons of the dashboard itself are exported from alinea/dashboard/icons.

Theme tokens

The components are styled with CSS custom properties. alinea/css declares them, and its resets, only on elements with a data-alinea-theme attribute, so loading the stylesheet doesn't restyle the rest of a page. The dashboard sets the attribute on <html>, and popovers, dialogs and tooltips set it on themselves since they render outside the page. To use the components on a page of your site, import alinea/css and render them inside an element with data-alinea-theme. Add data-theme="light" or data-theme="dark" to that element to fix the color scheme, otherwise it follows the page.

A theme only sets the inputs, as light-dark() pairs where a value differs per color scheme. Every other token is derived from them. Set them on the element with data-alinea-theme, for example <div data-alinea-theme className="brand-theme">:

.brand-theme {
  --alinea-radius: 6px;
  --alinea-bg: light-dark(#ffffff, #18181b);
  --alinea-fg: light-dark(#27272a, #e4e4e7);
  --alinea-primary: light-dark(#2f6b45, #5fbf82);
}

Popovers, dialogs and tooltips render outside that element and carry the attribute themselves, so a class on the page doesn't reach them: use [data-alinea-theme] as the selector to theme every part of the components on a page.

Inputs:

• --alinea-font, --alinea-mono-font, --alinea-font-size-base and --alinea-radius.

• --alinea-backdrop (behind panels), --alinea-bg (panels), --alinea-fg (text) and --alinea-border.

• --alinea-primary, --alinea-danger, --alinea-warning and --alinea-success, with --alinea-primary-fg, --alinea-danger-fg and --alinea-warning-fg for text on them.

• --alinea-ring: the focus ring.

• --alinea-workspace-color: the color option of the current workspace, set by the dashboard. It falls back to --alinea-primary.

Derived tokens, to read in your own styles:

• Text: --alinea-fg-strong, --alinea-fg-muted, --alinea-fg-disabled and --alinea-field-label.

• Surfaces: --alinea-bg-muted, --alinea-muted (hover backgrounds), --alinea-input, --alinea-overlay, --alinea-scrim (behind dialogs) and --alinea-border-strong.

• Tones: --alinea-selected and --alinea-selected-fg, and a -subtle background with a -subtle-fg text color for primary, danger, warning and success, eg. --alinea-danger-subtle.

• Entry statuses: --alinea-status-published, --alinea-status-draft and --alinea-status-unpublished, each with a -fg color.

• Shape and motion: --alinea-radius-sm, --alinea-radius-lg, --alinea-radius-xl, --alinea-shadow-raised, --alinea-shadow-muted, --alinea-shadow-tooltip, --alinea-shadow-modal and --alinea-transition.

The color palette the default theme is built from (--alinea-gray-500, --alinea-blue-800, ...) is not part of this list and can change.