https://github.com/datum-cloud/datum-ui
Datum Cloud's design system and React component library.
https://github.com/datum-cloud/datum-ui
graphql nextjs typescript ui
Last synced: about 1 month ago
JSON representation
Datum Cloud's design system and React component library.
- Host: GitHub
- URL: https://github.com/datum-cloud/datum-ui
- Owner: datum-cloud
- License: mit
- Created: 2026-01-22T14:43:26.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-07T05:45:59.000Z (about 2 months ago)
- Last Synced: 2026-05-07T07:38:24.195Z (about 2 months ago)
- Language: TypeScript
- Homepage: https://www.datum.net
- Size: 1.8 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Datum UI
Datum Cloud Design System & Component Library
---
## About
Datum UI is Datum Cloud's design system and React component library. It provides themed, composable components built on [shadcn/ui](https://ui.shadcn.com), [Radix UI](https://www.radix-ui.com), and [Tailwind CSS v4](https://tailwindcss.com) with a Figma-driven design token pipeline.
### Key Features
- **50+ Components** — Buttons, forms, data tables, dialogs, maps, typography, navigation, and more
- **Two-Layer Architecture** — shadcn/Radix primitives (base) + Datum-customized components (features)
- **Compound Form System** — Built on Conform.js and Zod with validation, field arrays, and multi-step support
- **Interactive Maps** — SSR-safe Leaflet integration with drawing tools, layers, clustering, and fullscreen
- **Task Queue** — Background task engine with progress UI, retry logic, and summary dialogs
- **Design Token Pipeline** — Figma tokens → purpose tokens → theme classes
- **Dark Mode** — Built-in theme provider with system preference detection
- **TypeScript** — Fully typed with exported types for all components
### Built With
- **React 19** — Latest React with server component support
- **Tailwind CSS v4** — Utility-first CSS framework
- **Radix UI** — Accessible, unstyled primitives
- **shadcn/ui** — Component foundation layer
- **CVA** — Class-variance-authority for variant-based component APIs
- **Conform.js + Zod** — Form state management and schema validation
---
## Monorepo Structure
```
packages/
datum-ui/ # Component library (@datum-cloud/datum-ui)
shadcn/ # shadcn/ui primitives (@repo/shadcn)
config/ # Shared config (TypeScript, Tailwind, ESLint)
apps/
docs/ # Fumadocs documentation site
storybook/ # Storybook component explorer
```
| Package | Description | npm |
|---|---|---|
| `@datum-cloud/datum-ui` | Published component library | [](https://www.npmjs.com/package/@datum-cloud/datum-ui) |
| `@repo/shadcn` | Internal shadcn/ui primitives | — |
| `@repo/config` | Shared TypeScript, Tailwind, and ESLint config | — |
---
## Prerequisites
- **Node.js >= 24** — Required for ESM module resolution with pnpm's strict dependency linking
- **pnpm >= 10** — Monorepo package manager
## Quick Start (Development)
```bash
# Clone and install
git clone https://github.com/datum-cloud/datum-ui.git
cd datum-ui
pnpm install
# Start Storybook (component explorer)
pnpm --filter @repo/storybook dev
# Start documentation site
pnpm --filter @repo/docs dev
# Build the component library
pnpm --filter @datum-cloud/datum-ui build
# Run all checks
pnpm --filter @datum-cloud/datum-ui typecheck
pnpm --filter @datum-cloud/datum-ui lint
pnpm --filter @datum-cloud/datum-ui test
```
> **Note:** Apps auto-build `@datum-cloud/datum-ui` before starting via a `predev` script.
---
## Usage (Consumers)
Install the package:
```bash
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
```
Add datum-ui styles to your CSS file, after Tailwind:
```css
@import 'tailwindcss';
@import '@datum-cloud/datum-ui/styles';
```
Wrap your app with `ThemeProvider` for light/dark/system switching:
```tsx
import { ThemeProvider } from '@datum-cloud/datum-ui/theme'
import { Button, Input } from '@datum-cloud/datum-ui'
function App() {
return (
Submit
)
}
```
### Entry Points
| Import Path | Description |
|---|---|
| `@datum-cloud/datum-ui` | All components, hooks, and utilities |
| `@datum-cloud/datum-ui/styles` | CSS (fonts, tokens, theme variables, component styles) |
| `@datum-cloud/datum-ui/theme` | `ThemeProvider`, `useTheme` |
| `@datum-cloud/datum-ui/hooks` | `useCopyToClipboard`, `useDebounce` |
| `@datum-cloud/datum-ui/icons` | `CloseIcon`, `IconWrapper`, `SpinnerIcon` |
| `@datum-cloud/datum-ui/utils` | `cn` (className merge utility) |
### Peer Dependencies
All peer dependencies are **optional** — install only what you use.
> Replace `npm install` with `yarn add`, `pnpm add`, or `bun add` for your package manager.
```bash
# Core (required)
npm install react react-dom
# Forms
npm install @conform-to/react @conform-to/zod zod
# Maps
npm install leaflet react-leaflet leaflet-draw leaflet.fullscreen leaflet.markercluster react-leaflet-markercluster
# Charts
npm install recharts
# Date pickers
npm install react-day-picker date-fns date-fns-tz
# Animations
npm install motion
```
See the full peer dependency list in the [package README](packages/datum-ui/README.md).
---
## Component Overview
### Base Components (30)
Thin wrappers around shadcn/Radix primitives with Datum styling.
`Alert` · `Badge` · `Breadcrumb` · `Button` · `ButtonGroup` · `Calendar` · `Card` · `Chart` · `Checkbox` · `Collapsible` · `Command` · `Dialog` · `HoverCard` · `Input` · `InputGroup` · `Label` · `Map` · `PlaceAutocomplete` · `Popover` · `RadioGroup` · `Select` · `Separator` · `Sheet` · `Skeleton` · `Spinner` · `Switch` · `Table` · `Tabs` · `Textarea` · `Tooltip` · `Typography` · `VisuallyHidden`
### Feature Components (18)
Complex, fully-customized components with significant business logic.
`Autocomplete` · `AvatarStack` · `CalendarDatePicker` · `Dropdown` · `Dropzone` · `EmptyContent` · `FileInputButton` · `Form` · `Grid` · `InputNumber` · `InputWithAddons` · `LoaderOverlay` · `MoreActions` · `NProgress` · `PageTitle` · `Sidebar` · `Stepper` · `TagInput` · `TaskQueue` · `TimeRangePicker` · `Toast`
For the complete component API with props, sub-components, and usage examples, see the [package README](packages/datum-ui/README.md).
---
## Documentation
- **[Package README](packages/datum-ui/README.md)** — Full component catalog, API reference, and usage examples
- **[Documentation Site](apps/docs/)** — Component docs, guides, and live previews
- **[Storybook](apps/storybook/)** — Interactive component explorer
---
## Contributing
```bash
# 1. Create a feature branch
git checkout -b feat/my-feature
# 2. Make changes and verify
pnpm --filter @datum-cloud/datum-ui build
pnpm --filter @datum-cloud/datum-ui typecheck
pnpm --filter @datum-cloud/datum-ui lint
pnpm --filter @datum-cloud/datum-ui test
# 3. Add a changeset to describe your changes
pnpm changeset
# Follow the prompts:
# - Select packages that changed (usually @datum-cloud/datum-ui)
# - Choose version bump type (patch/minor/major)
# - Write a summary of changes (becomes changelog entry)
# 4. Commit and push (include the changeset file)
git add .
git commit -m "feat: description of changes"
git push -u origin feat/my-feature
```
### Release Workflow
This project uses [Changesets](https://github.com/changesets/changesets) for version management and releases.
**For Contributors:**
When making changes, add a changeset to document what changed:
```bash
pnpm changeset
```
Choose the version bump type:
- **patch** — Bug fixes, minor updates (`0.3.2` → `0.3.3`)
- **minor** — New features, backward-compatible (`0.3.2` → `0.4.0`)
- **major** — Breaking changes (`0.3.2` → `1.0.0`)
Commit the generated `.changeset/*.md` file with your PR.
**For Maintainers:**
1. After PRs are merged, a "Version Packages" PR is automatically created
2. Review the PR to see version bumps and changelog
3. When ready to release:
- Merge the "Version Packages" PR
- Create a [GitHub Release](https://github.com/datum-cloud/datum-ui/releases)
- GitHub Actions automatically publishes to npm
**Renovate PRs:**
Dependency update PRs from Renovate automatically include changesets — no manual action needed.
For detailed workflow documentation, see [.github/RELEASE_WORKFLOW.md](.github/RELEASE_WORKFLOW.md).
## License
Datum UI is licensed under the [MIT License](https://github.com/lmsqueezy/wedges/blob/main/LICENSE).