@cdx-ui/components

Styled, theme-aware UI components for the Forge Design System.

Built on top of @cdx-ui/primitives, @cdx-ui/utils, @cdx-ui/icons, and @cdx-ui/formatters, styled via Uniwind + CVA. Design tokens from @cdx-ui/styles are consumed at the app level (not a direct package dependency).

Installation

pnpm add @cdx-ui/components

Peer dependencies

• react ^18.2.0 or ^19.0.0
• react-native >= 0.76.0 (optional — for native targets)
• react-native-web >= 0.19.0 (optional — for web targets)
• react-native-safe-area-context >= 4.0.0 — required for SafeAreaView and useSafeAreaInsets re-exports
• react-native-gesture-handler >= 2.0.0 (optional — required for Dialog/AlertDialog swipe-to-dismiss and ReorderableList)
• react-native-reanimated >= 4.0.0 (optional — required for BottomSheet, Skeleton, Carousel, Dialog, AlertDialog, Drawer, and ReorderableList)
• react-native-worklets >= 0.4.0 (optional — required alongside react-native-reanimated for animated components such as Dialog)
• @shopify/flash-list >= 2.0.0 (optional — required for VirtualizedList)
• react-native-sortables ^1.10.1 (optional — required for ReorderableList from @cdx-ui/components/reorderable-list on native)
• @dnd-kit/core ^6.3.0, @dnd-kit/sortable ^10.0.0, @dnd-kit/utilities ^3.2.0 (optional — required for ReorderableList from @cdx-ui/components/reorderable-list on web)
• react-native-svg ^13.0.0 || ^14.0.0 || ^15.0.0 (optional — required for ProgressCircle)

Note: uniwind (1.10.x) is a direct dependency — it is bundled automatically and does not need to be installed separately.

Usage

import { Button } from '@cdx-ui/components';

export function Example() {
  return (
    <Button variant="solid" color="action" size="default" onPress={() => console.log('pressed')}>
      <Button.Label>Get Started</Button.Label>
    </Button>
  );
}

Components

The component reference is the source of truth for the catalog — every component has a page there with live examples, props, and accessibility notes.

The package also ships that reference as markdown in docs/, matched to the installed version; coding agents should start at AGENTS.md in the package root.

Use Box for layout containers. The View re-export below is deprecated.

Providers

Wrap your app (or the Forge UI section of it) with the top-level provider so overlays, toasts, and global settings work:

| Export | Description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | ForgeDesignProvider | Top-level provider — configures global animation and text settings, the toast system, and portal/overlay management. Accepts a config prop. | | ToastProvider | Standalone toast host/queue context (already included by ForgeDesignProvider). | | useToast | Hook to imperatively show and dismiss toasts. |

ForgeDesignConfig and ForgeDesignProviderProps types are exported alongside ForgeDesignProvider.

Hooks and navigation

| Export | Description | | ---------------------------------- | ---------------------------------------------------------------------- | | useForgeBottomTabScreenOptions | Generates Forge-themed screen options for React Navigation bottom tabs | | mergeForgeBottomTabScreenOptions | Merges Forge bottom-tab options with consumer overrides | | forgeTabIcon | Creates a tab icon descriptor for native bottom tabs |

Metro configuration helper

The withForgeMetroConfig helper now ships from @cdx-ui/native, not this package — it is native build tooling, and keeping it here forced a Metro dependency onto every consumer of the component library.

const { withForgeMetroConfig } = require('@cdx-ui/native/metro');

module.exports = withForgeMetroConfig(config, {
  cssEntryFile: './global.css',
  generatedTypesFile: './uniwind-types.d.ts', // optional
});

withForgeMetroConfig must be the outermost wrapper if you compose multiple Metro config helpers.

React Native re-exports

For convenience, the package re-exports several core RN components and hooks with Uniwind className support:

| Export | Source | | ---------------------- | -------------------------------- | | View (deprecated) | react-native | | ScrollView | react-native | | KeyboardAvoidingView | react-native | | SafeAreaView | react-native-safe-area-context | | useSafeAreaInsets | react-native-safe-area-context |

Figma Code Connect

Template files under src/figma/ map Figma component variants to production Forge UI snippets shown in Figma Dev Mode. These files are excluded from the npm tarball (!src/figma in files) and published to Figma via CI on pushes to main. Conventions, property-mapping patterns, and the local workflow are documented in the repository's Code Connect authoring guide.

Testing

Tests live under __tests__/. This package uses two of the repo-root jest.config.js projects: rntl (jest-expo native + @testing-library/react-native) for *.test.tsx, and axe (jest-expo web + jsdom + @testing-library/react + jest-axe) for *.axe.test.tsx — both targeting packages/components/__tests__/. The repository's testing guide documents the full multi-project model.

# From monorepo root
pnpm nx run @cdx-ui/components:test
# or
pnpm test:all

Production types use tsconfig.json; tests use tsconfig.test.json.

Authoring: the repository's testing guide covers RNTL vs DOM, fireEvent.press vs fireEvent.click, and file naming.

A11y-only ad-hoc (from packages/components):
pnpm exec jest --config ../../jest.config.js --testNamePattern="a11y"

License

MIT © 2026 Digital First Holdings LLC. The full license text ships in the package as LICENSE.