@gentleduck/primitives

Unstyled, accessibility-first UI primitives for React.

--- Unstyled, accessibility-first UI primitives for React. ## Why primitives - **50-92% smaller than Radix** - Alert Dialog: 1.6 KB vs 18.6 KB. Popover: 2.4 KB vs 19.6 KB. Dialog: 3.1 KB vs 10.6 KB. Shared internals (Slot, Presence, Popper, focus scope) load once instead of being duplicated per-package. - **Full keyboard navigation + ARIA compliance out of the box** - every component ships with correct roles, states, and keyboard interactions so you don't have to wire them yourself. - **Compound component pattern** - compose `Root`, `Trigger`, `Content`, and friends to build exactly the UI you need without prop drilling. - **Compatible with Radix API** - same naming, same `asChild` pattern, same `data-state` attributes. Migration from Radix is a namespace change in your imports. ## Components | Primitive | Description | | --- | --- | | `alert-dialog` | Modal dialog that requires user acknowledgment | | `arrow` | Positioning arrow for floating elements | | `avatar` | User avatar with image and fallback support | | `calendar` | Date grid with keyboard navigation and multi-view support | | `checkers` | Checkbox and switch toggle primitive | | `command` | Command palette with search filtering | | `context-menu` | Right-click context menu with submenus | | `dialog` | Modal and non-modal dialog windows | | `direction` | RTL/LTR direction provider | | `dismissable-layer` | Layer that dismisses on outside interaction | | `dropdown-menu` | Dropdown menu with submenus, checkboxes, and radio items | | `focus-scope` | Traps and manages focus within a boundary | | `hover-card` | Card triggered by hover with open/close delay | | `input-otp` | One-time password input with slots and separators | | `menu` | Base menu primitive used by dropdown, context, and menubar | | `menubar` | Horizontal menu bar with keyboard navigation | | `mount` | Deferred mounting with lifecycle callbacks | | `navigation-menu` | Site navigation with animated indicator and viewport | | `pagination` | Page navigation controls | | `popover` | Floating content anchored to a trigger | | `popper` | Low-level floating element positioning via Floating UI | | `portal` | Renders children into a DOM portal | | `presence` | Animate mount/unmount transitions | | `primitive-elements` | Base `Primitive` element factory (`asChild` support) | | `progress` | Determinate and indeterminate progress indicator | | `radio-group` | Radio button group with roving focus | | `roving-focus` | Roving tabindex focus management for groups | | `select` | Listbox-style select with typeahead and scroll buttons | | `sheet` | Slide-out panel (re-exports dialog internals) | | `slider` | Range slider with single or multiple thumbs | | `slot` | Merges props and ref onto a child element (`asChild` engine) | | `toggle` | Two-state toggle button | | `toggle-group` | Single or multi-select group of toggles | | `tooltip` | Accessible tooltip with provider-level delay | | `visibility-hidden` | Visually hidden element for screen readers | ## Quick Start ```bash npm install @gentleduck/primitives ``` ```tsx import * as Dialog from '@gentleduck/primitives/dialog' function Demo() { return ( Open Heading Body text here. Close ) } ``` ## Features - **`asChild` / Slot** - render any primitive as your own element via the `asChild` prop, powered by the `Slot` utility. - **`createContextScope`** - scoped React context factory that prevents cross-instance state leaks. - **`forwardRef` everywhere** - every component forwards refs for imperative access and composition. - **`data-slot` attributes** - every component root emits a `data-slot` for style targeting without class names. - **Presence animations** - the `Presence` primitive lets you animate enter/exit transitions before unmounting. - **Focus trapping** - `FocusScope` locks focus inside modals, dialogs, and popovers with configurable loop behavior. - **Dismiss layers** - `DismissableLayer` handles outside clicks, Escape key, and nested layer stacking. ## Documentation [gentleduck.org/docs/packages/duck-primitives](https://gentleduck.org/docs/packages/duck-primitives) ## License [MIT](./LICENSE)