@datum-cloud/datum-ui

Datum Cloud's React design system and component library. Themed, composable components built on shadcn/ui, Radix UI, and Tailwind CSS v4.

Install

npm install @datum-cloud/datum-ui
# or
yarn add @datum-cloud/datum-ui
# or
pnpm add @datum-cloud/datum-ui
# or
bun add @datum-cloud/datum-ui

Requirements

• React 19
• Tailwind CSS v4.0.7+ (v4.2.1+ recommended)

Setup

1. Import Styles

Add datum-ui styles to your CSS file, after Tailwind:

/* app.css */
@import 'tailwindcss';
@import '@datum-cloud/datum-ui/styles';

/* Optional — import only if you use these components */
@import '@datum-cloud/datum-ui/grid';
@import '@datum-cloud/datum-ui/nprogress';

datum-ui ships uncompiled CSS that is processed by your Tailwind build in a single pass. The styles import automatically configures Tailwind to scan datum-ui's components for class usage via @source, so utilities like bg-primary and text-foreground work out of the box.

2. Add ThemeProvider

Wrap your app with ThemeProvider for light/dark/system theme switching:

import { ThemeProvider } from '@datum-cloud/datum-ui/theme'

function App() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      {/* your app */}
    </ThemeProvider>
  )
}

Imports

Each component has its own subpath export. Import only what you need:

import { Button } from '@datum-cloud/datum-ui/button'
import { Dialog } from '@datum-cloud/datum-ui/dialog'
import { Form, FormField, FormInput } from '@datum-cloud/datum-ui/form'

This keeps your bundle small. Some components require additional dependencies — check the component tables below for what to install.

Shared Exports

Grouped Exports

Some components with shared heavy dependencies are grouped under a single subpath:

Components

Base Components

Thin wrappers around shadcn/Radix primitives with Datum styling. Radix UI dependencies are bundled — no additional installation required for these components.

Feature Components

Complex, fully-customized components with significant business logic.

Each component's tree-shakeable subpath is the kebab-case of its directory, e.g. @datum-cloud/datum-ui/multi-select, @datum-cloud/datum-ui/app-navigation, @datum-cloud/datum-ui/grouped-table. The picker family lives under @datum-cloud/datum-ui/picker (see Grouped Exports).

Usage Examples

Avatar

import { Avatar, AvatarImage, AvatarFallback } from '@datum-cloud/datum-ui/avatar'

// With image and fallback
<Avatar>
  <AvatarImage src="https://example.com/avatar.jpg" alt="User Name" />
  <AvatarFallback>UN</AvatarFallback>
</Avatar>

// Custom size
<Avatar className="size-16">
  <AvatarImage src="https://example.com/avatar.jpg" alt="User Name" />
  <AvatarFallback className="text-lg">UN</AvatarFallback>
</Avatar>

// Fallback only (no image)
<Avatar>
  <AvatarFallback>AB</AvatarFallback>
</Avatar>

Button

import { Button } from '@datum-cloud/datum-ui/button'

// Variants: type × theme
<Button type="primary" theme="solid">Save</Button>
<Button type="danger" theme="outline">Delete</Button>
<Button type="secondary" theme="ghost">Cancel</Button>

Typography

import { Title, Text, Paragraph, Code } from '@datum-cloud/datum-ui/typography'

<Title level={1}>Page Title</Title>
<Title level={3} color="primary">Section</Title>
<Text size="sm" color="secondary">Subtitle text</Text>
<Paragraph>Body paragraph with default styling.</Paragraph>
<Code copyable>npm install @datum-cloud/datum-ui</Code>

Form with Validation

The form system uses a pluggable adapter pattern. Wrap your app with an adapter, then use Form.* components as usual:

import { Form } from '@datum-cloud/datum-ui/form'
import { ConformAdapter } from '@datum-cloud/datum-ui/form/adapters/conform'
// or: import { RHFAdapter } from '@datum-cloud/datum-ui/form/adapters/rhf'
import { z } from 'zod'

const schema = z.object({
  name: z.string().min(1, 'Name is required'),
  role: z.enum(['admin', 'user']),
})

// Wrap your app once with an adapter
function App() {
  return (
    <ConformAdapter>
      <MyForm />
    </ConformAdapter>
  )
}

// Form code is identical regardless of adapter
function MyForm() {
  return (
    <Form.Root schema={schema} onSubmit={handleSubmit}>
      <Form.Field name="name" label="Name" required>
        <Form.Input />
      </Form.Field>
      <Form.Field name="role" label="Role" required>
        <Form.Select placeholder="Select a role">
          <Form.SelectItem value="admin">Admin</Form.SelectItem>
          <Form.SelectItem value="user">User</Form.SelectItem>
        </Form.Select>
      </Form.Field>
      <Form.Submit>Save</Form.Submit>
    </Form.Root>
  )
}

Map

import {
  Map, MapTileLayer, MapMarker, MapPopup, MapZoomControl,
} from '@datum-cloud/datum-ui/map'

<div className="h-[500px] w-full">
  <Map center={[51.505, -0.09]} zoom={13}>
    <MapTileLayer />
    <MapZoomControl position="topright" />
    <MapMarker position={[51.505, -0.09]}>
      <MapPopup>Hello from London!</MapPopup>
    </MapMarker>
  </Map>
</div>

Dialog

import {
  Dialog, DialogTrigger, DialogContent,
  DialogHeader, DialogTitle, DialogDescription,
} from '@datum-cloud/datum-ui/dialog'

<Dialog>
  <DialogTrigger asChild>
    <Button>Open</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Confirm</DialogTitle>
      <DialogDescription>Are you sure?</DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>

Toast

import { ThemeProvider } from '@datum-cloud/datum-ui/theme'
import { Toaster, useToast } from '@datum-cloud/datum-ui/toast'

function App() {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      <Toaster />
      <MyComponent />
    </ThemeProvider>
  )
}

function MyComponent() {
  const { toast } = useToast()
  return <Button onClick={() => toast.success('Saved!')}>Save</Button>
}

Task Queue

import {
  TaskQueueProvider, TaskQueueDropdown, useTaskQueue,
} from '@datum-cloud/datum-ui/task-queue'

<TaskQueueProvider config={{ concurrency: 3 }}>
  <TaskQueueDropdown />
  <MyComponent />
</TaskQueueProvider>

function MyComponent() {
  const { enqueue } = useTaskQueue()

  const handleUpload = () => {
    enqueue({
      id: 'upload-1',
      label: 'Uploading file.pdf',
      run: async () => { /* upload logic */ },
    })
  }

  return <Button onClick={handleUpload}>Upload</Button>
}

Theming

ThemeProvider supports light, dark, and system theme modes:

import { ThemeProvider } from '@datum-cloud/datum-ui/theme'

<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
  {children}
</ThemeProvider>

Access the current theme:

import { useTheme } from '@datum-cloud/datum-ui/theme'

const { theme, setTheme, resolvedTheme } = useTheme()

Peer Dependencies

Required

These dependencies are required to use datum-ui:

npm install react react-dom tailwindcss lucide-react

• React 19+ and React DOM 19+: Framework requirements
• Tailwind CSS v4 (v4.0.7+, v4.2.1+ recommended): Required for styling
• lucide-react: Icon library used throughout components

All Radix UI packages are bundled — you don't need to install them separately.

Optional (Component-Specific)

Many components require additional packages. Install only what you use:

Replace npm install with yarn add, pnpm add, or bun add for your package manager.

# Forms — Conform adapter
npm install @conform-to/react @conform-to/zod zod

# Forms — React Hook Form adapter (alternative)
npm install react-hook-form @hookform/resolvers zod

# Maps (Map, MapMarker, MapPopup, etc.)
npm install leaflet react-leaflet leaflet-draw leaflet.fullscreen leaflet.markercluster react-leaflet-markercluster

# Charts (ChartContainer, ChartTooltip, etc.)
npm install recharts

# Code editor (CodeEditor, CodeEditorTabs)
npm install @monaco-editor/react monaco-editor

# Date pickers (Calendar, CalendarDatePicker, TimeRangePicker)
npm install react-day-picker date-fns date-fns-tz

# File upload (Dropzone)
npm install react-dropzone

# Number formatting (InputNumber)
npm install react-number-format

# Stepper (multi-step flows)
npm install @stepperize/react

# Toast notifications (Toast, Toaster)
npm install sonner

# Progress bar (NProgress)
npm install nprogress

# Data grid (Grid - virtualized tables)
npm install @tanstack/react-virtual

# Data Table (DataTable component)
npm install @tanstack/react-table

# Data Table with URL state (optional)
npm install nuqs

# Animations (motion components)
npm install motion

Form Adapters

The form system supports pluggable adapters. Choose one and wrap your app:

The Form.* component API is identical with either adapter. Switch adapters by changing only the root provider -- no form code changes needed.

See the Form README for detailed documentation.

Tech Stack

• React 19 with server component support
• Tailwind CSS v4 (v4.0.7+) for styling — ships uncompiled CSS processed by consumer's build
• Radix UI for accessible primitives
• CVA (class-variance-authority) for variant-based component APIs
• TypeScript — fully typed with exported types

Links

• GitHub
• npm

License

MIT

Optional: Canela font

Datum-branded surfaces can opt into Canela Text for the font-title Tailwind utility:

import '@datum-cloud/datum-ui/styles/canela'

Consumers who do not import this file use the default system font stack declared in tokens — no visual degradation.