Author UI Primitives

Author UI Primitives

Use this skill when building or revising packages/ui primitive APIs. The public @remix-run/ui/* entries are sourced from packages/ui/src/* and are not available through the remix package.

Source Layout

Each public primitive has a top-level packages/ui/src/<name>.ts or packages/ui/src/<name>.tsx entry.

Common files:

• <name>.ts or <name>.tsx: the public primitive entry and implementation.
• <name>/README.md: usage docs for the primitive.
• <name>.test.ts or <name>.test.tsx: primitive tests.
• demos/<name>.demo.tsx: demo cases for the shared UI demo app.
• lib/*: shared implementation-only behavior used by multiple primitives.

Current examples:

• low-level behavior modules: anchor, popover, listbox
• composed behavior modules: combobox, menu, select
• self-contained controls: accordion, tabs, toggle

When adding or moving public entries, update both exports and publishConfig.exports in packages/ui/package.json. Public entries use the flat ./<name> path.

Layering

Choose the smallest layer that fits the job.

• A headless primitive owns behavior, ARIA, registration, keyboard handling, refs, and public events. It exports named providers and mixins.
• A shared primitive utility belongs in src/lib only when multiple primitives already need it.

Good composition flows downward:

• select composes popover and listbox.
• combobox composes popover and listbox, then owns input text, filtering, and popup timing.
• menu composes popover, outside interactions, typeahead, and hover aim.
• accordion, tabs, and toggle keep their own primitive contexts.

Public API Shape

Primitive modules export named bindings, and callers namespace them at import time:

import * as select from '@remix-run/ui/select'

function StatusSelect() {
  return () => (
    <select.Context defaultLabel="Status">
      <button type="button" mix={select.trigger()} />
      <div mix={select.popover()}>
        <div mix={select.list()}>
          <div mix={select.option({ label: 'Open', value: 'open' })}>Open</div>
        </div>
      </div>
    </select.Context>
  )
}

Use Context, ItemContext, or GroupContext for providers, and short role names for mixins such as trigger, popover, list, option, hiddenInput, root, item, content, panel, parent, or control.

Do not add a public namespace object just to group exports. The established pattern is named exports plus import * as name.

README examples should import primitives from @remix-run/ui/... and component APIs from remix/component. Source files in this package import other primitive APIs from @remix-run/ui/... and component APIs from @remix-run/component.

Component Runtime

Primitive components use the current Remix component two-phase shape:

export function Component(handle: Handle<ComponentProps>): () => RemixNode {
  let hasInitialized = false
  let value: string | null = null

  return () => {
    if (!hasInitialized) {
      value = handle.props.defaultValue ?? null
      hasInitialized = true
    }

    return handle.props.children
  }
}

Rules:

• Read props from the stable handle.props object in setup and render code.
• Keep component lifetime state in setup scope and schedule renders with handle.update().
• Initialize uncontrolled state lazily from handle.props during the first render when defaults depend on current props or registered children.
• Await handle.update() before DOM work that depends on the next rendered tree; check the returned signal before continuing async flows.
• Use handle.queueTask() for post-render ref callbacks, registration checks, popup show/hide work, CSS-transition follow-up, and public ref delivery.

Context Providers

Providers scope one behavior instance. Prefer plain context objects with getters and methods over controller classes.

Use context for:

• current prop-backed state through getters
• registered descendants, root nodes, trigger nodes, surfaces, and lists
• methods such as open(), close(), navigate(), select(), highlight(), toggleItem(), or setInputText()
• stable public refs backed by getters and methods

Provider patterns:

• Call handle.context.set(...) once in setup scope when the object can stay stable.
• Reset render-scoped registries in the render function when children re-register each render.
• Use a "next registry" plus a queued comparison when child registration changes should trigger a follow-up render.
• Use nested item providers when one item needs per-item context, like AccordionItemProvider.
• Return handle.props.children unless the provider must compose lower-level providers, like SelectProvider returning listbox.Context.

Do not add event emitters to context just to wake descendants. Normal component updates, getters, and context methods are the default coordination layer.

Mixins

Mixins adapt one host element to one behavior role.

Use createMixin with explicit host, argument, and prop types:

const triggerMixin = createMixin<HTMLButtonElement, [], ElementProps>((handle) => {
  let context = handle.context.get(SelectProvider)

  return (props) => [
    attrs({
      'aria-haspopup': 'listbox',
      'aria-expanded': context.isExpanded ? 'true' : 'false',
      disabled: context.disabled ? true : props.disabled,
    }),
    ref((node: HTMLButtonElement, signal) => {
      context.registerTrigger(node)
      signal.addEventListener('abort', () => {
        context.unregisterTrigger(node)
      })
    }),
    on('click', () => {
      context.open()
    }),
  ]
})

Mixin rules:

• Own one role and one host element.
• Derive ARIA, data-*, hidden, disabled, tabIndex, and ids from context getters.
• Normalize DOM input locally, then call context methods.
• Keep role-specific keyboard parsing in the role mixin.
• Register host nodes with ref(...), handle.queueTask(...), or an insert listener, and clean up registrations with the abort signal when needed.
• For mixins that support both native inputs and custom elements, use hostType, createElement(...), or renderMixinElement(...) to rewrite props safely.

If a mixin accepts optional options and also receives host props, follow the existing options = {}, props = options as ElementProps pattern when needed to distinguish authored options from host props.