@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-reanimated >= 4.0.0 (optional — required for BottomSheet, Skeleton, Carousel, Dialog, and AlertDialog)
• react-native-worklets >= 0.4.0 (optional — required alongside react-native-reanimated for animated components such as Dialog)
• react-native-gesture-handler >= 2.0.0 (optional — required for Dialog/AlertDialog swipe-to-dismiss)
• @shopify/flash-list >= 2.0.0 (optional — required for VirtualizedList)

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>
  );
}

Component stories live in apps/storybook. See the full component reference for per-component docs.

Components

Accordion, Alert, AlertDialog, Avatar, Badge, BottomSheet, Breadcrumbs, Button, Calendar, Card, Carousel, Checkbox, Chip, CurrencyInput, DateField, DatePicker, DateRangePicker, DateTimeField, DateTimeList, DateTimePicker, Dialog, Divider, Field, Form, Heading, HStack / VStack, Icon, IconButton, Image, Input, InsuranceDisclosure, Link, ListItem, Menu, MonthCalendar, MonthPicker, OtpInput, ProgressBar, ProgressCircle, ProgressSegmented, QuickActionButton, Radio, RangeCalendar, ScopedTheme, ScrollShadow, Select, Skeleton, Slider, Switch, Tabs, Text, Textarea, Tile, Toast, Tooltip, VirtualizedList.

Box is exported but deprecated — use React Native's View directly.

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/metro, 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 | 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 in 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.

See the Code Connect authoring guide for conventions, property mapping patterns, and local workflow.

Testing

Tests live in __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 root config defines seven projects in total; see docs/internal/testing.md for the full 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: See docs/internal/testing.md (RNTL vs DOM, fireEvent.press vs fireEvent.click, 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. See LICENSE for details.