@cdx-ui/utils

Shared utilities used across CDS packages.

Provides common helpers for styling, event handling, state management, and context propagation used by @cdx-ui/primitives and @cdx-ui/components.

Installation

pnpm add @cdx-ui/utils

Exports

Common helpers

| Export | Description | | --- | --- | | cn(...inputs) | Merges class names with clsx + tailwind-merge — conditionals and conflict resolution in one call. | | composeEventHandlers(...handlers) | Chains multiple event callbacks into a single handler; skips null/undefined entries. | | useControllableState(params) | Hook that supports both controlled and uncontrolled modes for a single value. Warns in dev if the mode switches during a component's lifetime. | | mergeRefs(...refs) | Combines multiple refs (callback or object) into one ref callback. | | flattenChildren(children) | Recursively flattens React children into a flat array (used internally for spaced-child layouts). | | ariaAttr(condition) | Returns 'true' or undefined — shorthand for boolean ARIA attribute values. |

Context

| Export | Description | | --- | --- | | createContext(displayName) | Wrapper around React's createContext that returns a [Provider, useHook] tuple. The hook throws a descriptive error if called outside the provider — eliminates silent undefined bugs. |

Style context

Used internally by @cdx-ui/components to propagate variant props (size, color, etc.) from a compound root to its sub-components.

| Export | Description | | --- | --- | | withStyleContext(Component, scope?) | HOC that adds a context prop and provides it to descendants via ParentContext. | | useStyleContext(scope?) | Reads the style context set by the nearest withStyleContext wrapper. | | useParentContext() | Reads the full StyleContextMap from the nearest provider. | | ParentContext | The raw React context (rarely needed directly). |

Form control

Low-level form-field state used by the Field and Input primitives.

| Export | Description | | --- | --- | | useFormControlRoot(props) | Creates the root state object for a form field (id generation, aria-describedby wiring). | | useFormControl(props) | Merges component-level props with inherited form-control context. | | useFormControlContext() | Reads form-control state from the nearest provider. | | FormControlContext | The raw React context for form-control state. |

Further reading

• State management practices — useControllableState and composeEventHandlers patterns
• Styling practices — cn() and CVA variant authoring