@bx-labs/bx-ui

Banxa's React design system — a set of accessible, themeable UI components built on a three-tier CSS custom property token cascade (primitives → semantic → component), with first-class TypeScript support and a dark-mode-first theme that can be fully overridden by consuming applications.

This is the React port of @banxa-official/banxa-ui (Vue 3). Both packages render the same markup, share the same class names, and consume the same token stylesheet, so a product can migrate framework-by-framework without a visual break.

Installation

npm install @bx-labs/bx-ui

react and react-dom (^18 or ^19) are peer dependencies and must already be installed. The package itself ships zero runtime dependencies.

Getting started

Import the components you need and the stylesheet once, globally, in your app's entry point:

// main.tsx
import { createRoot } from 'react-dom/client'
import App from './App'
import '@bx-labs/bx-ui/style.css'

createRoot(document.getElementById('root')!).render(<App />)

Then use components directly:

import { useState } from 'react'
import { BxButton, BxInput } from '@bx-labs/bx-ui'

export default function SignUp() {
  const [email, setEmail] = useState('')

  return (
    <>
      <BxInput value={email} onChange={setEmail} label="Email address" placeholder="[email protected]" />
      <BxButton variant="primary" onClick={submit}>Continue</BxButton>
    </>
  )
}

Only import what you use — the library is tree-shakeable, so unused components are dropped from your production bundle.

Available components

| Category | Components | |------------|------------| | Foundation | BxButton, BxIcon, BxDivider, BxBadge | | Form | BxInput, BxSelect, BxSelectField, BxCombobox, BxCheckbox, BxRadio, BxSwitch, BxOtpInput | | Feedback | BxAlert, BxToast, BxProgress, BxSpinner, BxDots, BxSkeleton | | Surface | BxCard, BxModal, BxTooltip, BxDescriptionList | | Navigation | BxDropdownMenu, BxDropdownMenuItem, BxTabs | | Composite | BxCollapsible |

Browse every component, prop, and variant interactively in Storybook.

Differences from the Vue package

The rendered DOM, class names, and tokens are identical. The API is idiomatic React:

| Vue | React | |-----|-------| | v-model="x" | value={x} onChange={setX} — plus defaultValue for uncontrolled use | | @click="fn" | onClick={fn} | | <slot /> | children | | <slot name="left-item" /> | leftItem prop (ReactNode) | | scoped slot v-slot="{ item }" | render prop, e.g. renderOption={(item) => ...} | | emit('close') | onClose prop |

Every component forwards its ref to the underlying root element and spreads unrecognised props onto it, so className, data-*, and event handlers pass through as expected.

Theming

Components never hardcode colours — every visual token is a CSS custom property, applied at three tiers:

1. Primitives — raw palette/scale values (--space-16, --radius-standard, ...)
2. Semantic — what things mean (--fills-cta, --fills-background, --fills-alert-error, ...)
3. Component — per-component hooks for narrow overrides (--bx-button-bg, ...)

The library ships dark mode by default (tokens on :root) and a light mode you opt into by adding a .lightmode class to any ancestor element (typically <html> or <body>):

document.documentElement.classList.toggle('lightmode', isLightMode)

Overriding colours (brand/merchant theming)

Because every token is a real CSS custom property, a host application can override the whole palette without touching component code — just redeclare the variables on an ancestor element, after the library's stylesheet has loaded:

:root {
  --fills-cta: #ff5a1f;
  --fills-cta-hover: #e64f1a;
  --fills-cta-active: #cc4517;
  --fills-cta-foreground: #ffffff;
  --fills-background: #0b0b0d;
}

This works because CSS custom properties resolve via normal inheritance: a declaration on a container element always wins over an inherited value from :root, regardless of stylesheet load order — so it's safe to apply per-tenant/per-merchant theming at runtime (e.g. via element.style.setProperty('--fills-cta', merchantColor)).

TypeScript support

The package ships its own type declarations (dist/index.d.ts, generated from source) — no @types/* package needed. Component props, exported hooks, and shared types are all available out of the box:

import { BxSelect } from '@bx-labs/bx-ui'
import type { SelectOption, BxSelectProps } from '@bx-labs/bx-ui'

const options: SelectOption[] = [
  { label: 'USD', value: 'usd' },
  { label: 'EUR', value: 'eur' }
]

moduleResolution: "bundler" or "node16"/"nodenext" (TS ≥ 4.7) is recommended so the package's exports map resolves correctly.

Error handling

Banxa UI surfaces problems in two different ways depending on whether they're part of your app's normal control flow or a mistake in how a component is used:

• Validation / user-facing errors are just props — there are no exceptions to catch. Pass an error message (or boolean, depending on the component) and the component renders its error styling and, where applicable, wires up aria-describedby / role="alert" for screen readers:

  <BxInput value={email} onChange={setEmail} label="Email" error={emailError} />
  <BxButton variant="outlined" error>Delete account</BxButton>

• Developer-facing warnings (deprecated props, unknown icon names, etc.) are logged via console.warn and are automatically stripped out of production builds (import.meta.env.DEV guarded), so they never ship to end users:

  [BxInput] "hint" is deprecated. Use "description" instead.
  [BxIcon] Unknown icon name: "not-a-real-icon". Register it in registry.ts.

  Treat these as build-time linting signals — fix them before shipping, not something to handle at runtime.

Components do not throw during normal rendering; malformed input (e.g. an unrecognised icon name) degrades gracefully (renders a sizing placeholder) rather than crashing your app.

Storybook

Every component has a live, interactive Storybook entry with all variants and a dark/light theme toggle.

git clone [email protected]:banxa/banxa-ui.git
cd banxa-ui/react
npm install
npm run storybook       # http://localhost:6007

The Vue Storybook runs on port 6006 and the React one on 6007, so both can run side by side when comparing parity.

Development

npm run dev              # Vite dev server
npm run build            # Build the library (dist/)
npm run typecheck        # tsc --noEmit
npm run test             # Vitest + Testing Library
npm run lint             # ESLint with --fix
npm run lint:check       # ESLint, no autofix (CI)

Publishing

This package publishes independently of the Vue one. Releases are built from dist/ (never commit dist/ — it's generated by npm run build, which also runs automatically via prepublishOnly before npm publish).

cd react
npm version <patch|minor|major>
npm publish

Browser support

Targets evergreen browsers (Chrome, Firefox, Safari, Edge — last 2 versions). No IE11 support.

License

MIT