@structyl/primitives

Headless, accessible React behavior primitives — structure without styling.

@structyl/primitives is the headless behavior layer of structyl. It provides unstyled, WAI-ARIA compliant React components — dialogs, menus, selects, date pickers, and dozens more — that ship full keyboard navigation, focus management, and accessibility while leaving styling entirely up to you. It is the foundation that @structyl/styled builds on, and it's also a complete toolkit on its own for teams that bring their own design system.

Installation

# pnpm
pnpm add @structyl/primitives

# npm
npm install @structyl/primitives

# yarn
yarn add @structyl/primitives

React 18 or 19 (and the matching react-dom) are required as peer dependencies.

Usage

Multi-part components use a compound, dot-notation API. Every primitive is unstyled — apply your own classes or styles.

import { Dialog, Button } from '@structyl/primitives';

export function Example() {
  return (
    <Dialog.Root>
      <Dialog.Trigger asChild>
        <Button>Open dialog</Button>
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          <Dialog.Title>Confirm action</Dialog.Title>
          <Dialog.Description>This cannot be undone.</Dialog.Description>
          <Dialog.Close asChild>
            <Button>Cancel</Button>
          </Dialog.Close>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

Stateful primitives support both controlled and uncontrolled usage:

import { Dialog } from '@structyl/primitives';

// Uncontrolled
<Dialog.Root defaultOpen={false}>{/* ... */}</Dialog.Root>

// Controlled
<Dialog.Root open={open} onOpenChange={setOpen}>{/* ... */}</Dialog.Root>

Features

• Accessible by default — WAI-ARIA APG patterns, correct roles and attributes, and full keyboard support for every interaction.
• Headless — zero styling shipped; render with Tailwind, CSS Modules, or anything else.
• Compound APIs — composable dot-notation parts (Dialog.Root, Dialog.Trigger, Dialog.Content, …).
• asChild slots — merge behavior onto your own element or component instead of an extra wrapper.
• Controlled & uncontrolled — every stateful primitive works both ways via value/defaultValue plus change handlers.
• Ref forwarding — all primitives forward refs to their underlying DOM node.
• TypeScript-first — strict types and exported prop types for every component.
• SSR / RSC friendly — tested in the Next.js App Router.

API

The package exports both standalone primitives and namespaced compound components. A selection of the main exports:

Every component ships its corresponding prop types (for example ButtonProps, DialogContentProps, SelectRootProps). See the documentation for the full API reference.

Part of structyl

Part of the structyl component library — see the full docs at www.structyl.com.

License

MIT