@structyl/core

Headless React primitives that power the structyl component library.

@structyl/core is the low-level foundation underneath every styled component in structyl. It provides the unstyled, accessible building blocks — polymorphic elements, the asChild slot pattern, scoped contexts, focus management, presence/animation handling, and Floating UI–based positioning. If you are building your own headless components (or extending structyl), this is the package you compose from; most app authors will consume @structyl/primitives or @structyl/styled instead.

Installation

# pnpm
pnpm add @structyl/core

# npm
npm install @structyl/core

# yarn
yarn add @structyl/core

react and react-dom (v18 or v19) are peer dependencies.

Usage

Build a polymorphic, accessible primitive using Primitive (with built-in asChild) and a typed context created with createContext:

'use client';

import * as React from 'react';
import { Primitive, createContext } from '@structyl/core';

interface ToggleContextValue {
  pressed: boolean;
  onToggle: () => void;
}

const [ToggleProvider, useToggleContext] = createContext<ToggleContextValue>('Toggle');

function Toggle({ children }: { children: React.ReactNode }) {
  const [pressed, setPressed] = React.useState(false);
  return (
    <ToggleProvider pressed={pressed} onToggle={() => setPressed((p) => !p)}>
      {children}
    </ToggleProvider>
  );
}

const ToggleButton = React.forwardRef<
  HTMLButtonElement,
  React.ComponentPropsWithRef<typeof Primitive.button>
>((props, ref) => {
  const { pressed, onToggle } = useToggleContext('ToggleButton');
  return (
    <Primitive.button
      ref={ref}
      type="button"
      aria-pressed={pressed}
      data-state={pressed ? 'on' : 'off'}
      onClick={onToggle}
      {...props}
    />
  );
});
ToggleButton.displayName = 'ToggleButton';

// `asChild` renders the behavior on your own element instead of a <button>:
//   <ToggleButton asChild><MyLink href="/" /></ToggleButton>

Features

• Polymorphic Primitive — render Primitive.button, Primitive.div, etc., with first-class ref forwarding and an asChild prop on every node.
• Slot / Slottable — merge props, class names, styles, and event handlers onto a consumer-supplied child to implement asChild.
• Typed contexts — createContext, createContextScope, and composeContextScopes give descriptive errors outside a provider and avoid context leakage in nested or shared component families.
• Focus management — FocusScope traps and loops focus, and useFocusGuards inserts sentinel guards so Tab cannot escape an open layer.
• Layer dismissal — DismissableLayer handles Escape, outside-pointer, and outside-focus interactions for popovers, dialogs, and menus.
• Presence & animation — Presence / usePresence keep an element mounted until its exit CSS animation or transition finishes.
• Positioning — the Popper namespace wraps @floating-ui/react for anchored content with flip, shift, size, and arrow support.
• Roving focus & collections — RovingFocusGroup and createCollection provide arrow-key navigation over DOM-ordered items.
• Accessibility helpers — VisuallyHidden, AccessibleIcon, and DirectionProvider / useDirection for screen-reader labels and RTL awareness.
• SSR-safe — all browser access is guarded; primitives are marked 'use client' and work in the Next.js App Router.

API

Type definitions are exported alongside each component (e.g. PrimitivePropsWithRef, SlotProps, PortalProps, PresenceProps, Direction).

Part of structyl

This package is part of structyl — the React UI library with structure. See the full documentation at www.structyl.com.

License

MIT