Configuration

nake-ui keeps configuration close to each primitive instance. There is no global theme or layout provider required for behavior. Configure state, IDs, orientation, placement, disabled/invalid flags, collection data, and callbacks through the primitive or adapter surface you are using.

Global application concerns such as routing, analytics, i18n, CSS variables, animation timing, and product theme mode should stay outside the core behavior layer unless the primitive spec explicitly requires them.

IDs must be deterministic and hydration-safe. You can usually let the adapter generate IDs, but provide an explicit id when:

• SSR output must be stable across app routes.
• Multiple server/client render passes could allocate IDs in different order.
• You need predictable IDs for tests, validator fixtures, or agent repair.
• You are composing detached markup or external labels.

Bad ID hygiene breaks aria-controls, aria-labelledby, aria-describedby, and aria-activedescendant.

Use controlled state when the product owns the value:

<Tabs.Root value={value} onValueChange={setValue}>
  ...
</Tabs.Root>

Use uncontrolled state when the primitive can own the value:

<Tabs.Root defaultValue="overview">...</Tabs.Root>

Do not pass both value and defaultValue to the same state dimension after setup. If you need to migrate, do it deliberately and add a regression test for callback behavior.

Collection primitives need stable item identities:

• Tabs: stable tab values and matching panels.
• Menu: stable item IDs and textValue for typeahead.
• Listbox/Select/Combobox: stable option values and labels.

Avoid deriving IDs from array indexes when the collection can reorder, filter, or paginate. Reordering unstable IDs can move selection or highlight to the wrong item.

Floating primitives expose placement options through adapters:

• placement
• align for Popover
• offset
• viewportPadding
• matchAnchorWidth or matchTriggerWidth
• update strategy or manual sync hooks where supported

The DOM should reflect resolved layout through data-placement and data-side; Popover also reflects data-align.

Add validation where mistakes are likely:

pnpm content:check
pnpm test:contracts
pnpm --filter @nake-ui/devtools-validator test:unit

Application-level gates should include:

• ARIA linkage assertions.
• Keyboard interaction smoke tests.
• SSR/hydration snapshot for server-rendered routes.
• DOM contract snapshot for shared components.

• React, Vue, and Solid generally configure behavior through component props.
• Vanilla config is passed to bind* functions and updated through sync().
• Svelte config is passed to compound primitive namespace props and reactive bindings.
• Floating measurement and dismissable layer activation are client-side lifecycle concerns.

• Explicit IDs are used for SSR-sensitive or test-sensitive instances.
• Controlled and uncontrolled props are not mixed.
• Collection item IDs are stable.
• Floating options are reflected in public layout attributes.
• Validator and interaction tests cover the configured behavior.