@var-ui/react

React component library built with typestyles and @var-ui/core tokens. Consumed by the docs site and examples/vite-app.

Framework-specific wrappers around accessible primitives (React Aria Components) with typed variants, design tokens, and theme context.

Install

pnpm add @var-ui/react @var-ui/core react react-dom react-aria-components typestyles

Within this monorepo:

{
  "dependencies": {
    "@var-ui/react": "workspace:*"
  }
}

Peer dependencies: react, react-dom, react-aria-components, and @var-ui/core.

Usage

import { Button, DesignSystemProvider, layout, text } from '@var-ui/react';

export function App() {
  return (
    <DesignSystemProvider applyToDocument>
      <main className={layout({ stack: true })}>
        <h1 className={text({ title: true })}>Hello</h1>
        <Button intent="primary">Click me</Button>
      </main>
    </DesignSystemProvider>
  );
}

Import the package once in your extraction entry so all registrations land in production CSS:

// src/typestyles-entry.ts
import '@var-ui/react';
import './app-styles';

Icons

var-ui components never bundle SVGs. They resolve semantic icon names (close, chevronDown, search, info, …) through IconProvider; unmapped names render a single shared empty placeholder (correctly sized, zero payload).

1. Required — mount an IconProvider (icons come from the provider only):

import { DesignSystemProvider, IconProvider } from '@var-ui/react';

export function AppShell({ children }: { children: React.ReactNode }) {
  return (
    <DesignSystemProvider>
      {/* Pass at least an empty object — unmapped names use the empty fallback */}
      <IconProvider icons={{}}>{children}</IconProvider>
    </DesignSystemProvider>
  );
}

2. Optional — var-ui default glyphs (@var-ui/icons, optional peer):

pnpm add @var-ui/react @var-ui/core @var-ui/icons

import { defaultIcons } from '@var-ui/icons';

<IconProvider icons={defaultIcons}>
  <App />
</IconProvider>;

3. Alternative — bring your own icon library (no @var-ui/icons):

import { Check, ChevronDown, CircleAlert, CircleCheck, Copy, Info, Search, X } from 'lucide-react';
import type { IconName } from '@var-ui/core';

const lucideIcons: Partial<Record<IconName, React.ReactNode>> = {
  close: <X />,
  chevronDown: <ChevronDown />,
  search: <Search />,
  check: <Check />,
  copy: <Copy />,
  info: <Info />,
  success: <CircleCheck />,
  warning: <CircleAlert />,
  error: <CircleAlert />,
};

<IconProvider icons={lucideIcons}>
  <App />
</IconProvider>;

Per-component overrides bypass the registry (e.g. <Alert icon={<Custom />} />; pass icon={null} to hide a default glyph). Nested providers shallow-merge over the parent registry for their subtree. Use <Icon name="…" /> directly for your own UI, or <Icon>{node}</Icon> for one-off custom glyphs.

Exports

| Category | Examples | | -------------------- | ----------------------------------------------------------------------------------------------------- | | Actions & forms | Button, Link, TextField, TextAreaField, Checkbox, Switch, RadioGroup, Select, Field | | Layout | Stack / HStack / VStack, Grid, Section, Center, AspectRatio, Divider | | Content | Heading, Text, Timestamp, EmptyState, CodeBlock | | Containers | Card, ClickableCard, Carousel, Thumbnail, Avatar, AvatarGroup, Badge | | Feedback | Alert, Banner, Spinner, ProgressBar | | Overlay & nav | Dialog, Tabs | | Icons | Icon, IconProvider, useIcons (+ optional @var-ui/icons glyph package) | | Layers | LayerProvider, useLayer — z-index coordination for floating UI | | Hooks | useMediaQuery, useScrollLock | | Layout utilities | layout, text — re-exported from @var-ui/core | | Tokens | designTokens, typed value exports | | Theming | DesignSystemProvider, useColorMode, ColorModeToggle |

Core-only recipes without wrappers (use the class helpers from @var-ui/core): skeleton, statusDot, kbd, overlay, plus everything in the core README's inventory.

Side effect on import: @var-ui/core registers base document styles (see document-globals.ts).

Structure

src/
  components/     # React Aria–based UI
  icons/          # IconProvider, useIcons, Icon, empty fallback
  layers/         # LayerProvider / useLayer z-index coordination
  hooks/          # useMediaQuery, useScrollLock, …
  styles.ts       # re-exports layout + text from @var-ui/core
  tokens.ts       # Re-exports / aliases @var-ui/core tokens
  color-mode.tsx            # useColorMode, getColorModeInitScript
  DesignSystemProvider.tsx  # DesignSystemProvider
  index.ts        # Public API

Learn more

• @var-ui/core — framework-agnostic tokens and recipes
• Component libraries guide
• Vite example — consumes this package