@cdx-ui/primitives

Unstyled, accessible behavioral components (headless) for the Candescent Design System.

Primitives provide interaction logic, focus management, and accessibility without imposing any visual styling. They serve as the foundation for @cdx-ui/components.

Installation

pnpm add @cdx-ui/primitives

Peer dependencies

• react ^18.2.0 || ^19.0.0
• react-native >= 0.76.0 (optional)
• react-native-reanimated >= 3.0.0
• react-native-web >= 0.19.0 (optional)

Factory functions

Each create* factory accepts a map of base React Native components and returns a compound component with built-in interaction state tracking, accessibility (roles, ARIA props, keyboard handling), and context propagation.

| Factory | Returns | | ---------------- | ------------------------------------------------------------------------------------------------------- | | createButton | Button + .Text .Group .Spinner .Icon | | createInput | Input + .Slot .Field | | createSelect | Select + .Trigger .Value .Icon .Content .Item .ItemLabel | | createCheckbox | Checkbox + .Indicator .Icon .Label .Group | | createRadio | Radio + .Indicator .Label .Group | | createSwitch | Switch | | createLink | Link | | createAvatar | Avatar + .Image .Text .Icon .Badge | | createDialog | Dialog + .Root .Trigger .Content .Header .Title .Description .Body .Footer .Close | | createField | Field + .Label .Helper .HelperText .Error .ErrorText .ErrorIcon | | createForm | Form | | createListItem | ListItem + .LeadingSlot .Content .Title .Description .Meta .TrailingSlot .SectionHeader | | createOtpInput | OtpInput + .Cell .Field | | createProgress | Progress + .Indicator | | createTile | Tile + .Group .LeadingSlot .Content .Title .Description .Indicator .TrailingSlot |

Utility exports

| Export | Description | | ----------------------- | ------------------------------------------------------------------------------------------------- | | dataAttributes | Builds data-hover, data-active, data-focus-visible, etc. from an InteractionState object. | | OverlayInsetsProvider | Context provider for safe-area insets used by overlay/dialog positioning. | | InteractionState | Type: { hover, focus, active, disabled, focusVisible }. | | EdgeInsets | Type: { top, right, bottom, left }. |

Context hooks and providers

Several modules export context providers and hooks for reading component state from descendant sub-components or for integrating with external systems (e.g., routing).

| Module | Provider(s) | Hook(s) | Context value type(s) | | --------- | ------------------ | -------------------- | --------------------------------------------- | | dialog | DialogProvider | useDialog | IDialogContextType | | link | LinkProvider | useLink | LinkConfig | | tile | TileProvider | useTileContext | ITileContextValue, ITileGroupContextValue | | list-item | ListItemProvider | useListItemContext | IListItemContextValue | | button | — | useButtonContext | — | | progress | — | useProgressContext | ProgressContextValue |

Further reading

• Definitions — artifact taxonomy (primitive vs component vs utility)