@base-org/bds-web

React component library and icons for Base products, built on React Aria Components, Tailwind CSS v4, and CVA.

yarn add @base-org/bds-web @base-org/bds-tokens

Peer dependencies, if not already present:

yarn add react react-dom react-aria react-aria-components motion class-variance-authority @react-aria/collections @react-aria/utils @react-types/shared

React 19.3 or newer is required. Several components (Freeze, AnimateHeight, the metric card charts) depend on Fragment Refs, which only became stable in 19.3.

Setup

Your global CSS must import the spectrum tokens and register the BDS theme, and Tailwind must be pointed at the package so it can find the utility classes the components use:

@import 'tailwindcss';
@source "node_modules/@base-org/bds-web/dist";
@import '@base-org/bds-tokens/tokens/spectrum.css';

The full theme block, dark mode setup, focus ring styles, and skeleton animation keyframes are documented in the repository README.

Usage

Every component is a separate entry point — there are no barrel exports.

import { Button } from '@base-org/bds-web/components/button';
import { PlusIcon } from '@base-org/bds-web/icons/2.5/plus-icon';

<Button variant="primary" size="md" startIcon={<PlusIcon />}>
  Create
</Button>;

Icons are organised by stroke weight: icons/1.5/*, icons/2/*, icons/2.5/*, icons/fill/*, and icons/fill/1.5/*.

Conventions

• Merge props with mergeProps from react-aria; do not spread and override.
• Pass className directly. Components merge it internally — do not reach for cx or clsx.
• Do not size icons passed to slots (startIcon, endIcon, icon); components set icon sizes via IconPropsContext.
• Overridable properties use [:where(&)], so your Tailwind utilities win without !important.

Components

Badge, Banner, Button, Empty, Icon, Link, LinkButton, Menu, MetricCard, NumberField, Popover, Segment, Select, Skeleton, ShimmerOverlay, Spinner, Status, Switch, Tabs, TextField, ThemeProvider, ThemeToggle, Tooltip, Unread, AnimateHeight.