@cdx-ui/utils
Shared utilities used across FDS 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. Derives isControlled from whether the prop is undefined. |
mergeRefs(...refs) | Combines multiple refs (callback or object) into one ref callback. |
flattenChildren(children) | Recursively flattens React children (including Fragments) into a flat array with re-keyed elements. |
ariaAttr(condition) | Returns true (boolean) or undefined — shorthand for boolean ARIA attribute values. |
cva(base, config) | Class Variance Authority helper for authoring variant-driven className builders. VariantProps<typeof fn> derives the prop type. |
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 |
|---|---|
ParentContext | React context for propagating variant props from a compound root to sub-components. Wrap children in <ParentContext.Provider value={...}>. |
useStyleContext(scope?) | Reads the style context set by the nearest ParentContext.Provider. |
useParentContext() | Reads the full StyleContextMap from the nearest provider. |
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, tracks hasFeedbackText/hasHelpText for describedby assembly). |
useFormControl(props) | Merges component-level props with inherited form-control context. Assembles aria-describedby from feedback/help text ids. |
useFormControlContext() | Reads form-control state from the nearest provider. |
useReportFormControlLabelFocus(isActive) | Reports focus/active state to the parent FormControlContext — used by Input/Select.Trigger to trigger isFocused styling on the associated label. |
useReportFormControlValidation(isInvalid, errorMessage) | Reports a self-validating control's invalid state and message to the parent Field — used by DatePicker so Field.Error / Field.Helper anywhere in the field reflect it. |
FormControlContext | The React context object for form-control state propagation. |
Exported types
| Type | Source |
|---|---|
UseControllableStateParams | common |
VariantProps | common |
Focusable | form-control |
FormControlContextValue | form-control |
FormControlFieldProps | form-control |
FormControlRootProps | form-control |
FormControlRootReturn | form-control |
FormControlState | form-control |
FormControlValidation | form-control |
StyleContextMap | style |
Testing
Tests are colocated next to source files (*.test.{ts,tsx}). Run via the utils Jest project:
pnpm nx run @cdx-ui/utils:test
All runtime exports have test coverage using @testing-library/react-native (renderHook, act).
Further reading
The Forge UI docs site covers setup and usage. The repository's internal authoring guides cover the patterns behind these helpers — useControllableState and composeEventHandlers in the state guide, and cn() and CVA variant authoring in the styling guide.
License
MIT © 2026 Digital First Holdings LLC. The full license text ships in the package as LICENSE.