@vllnt/ui

React component library — 144 components built on Radix UI primitives, Tailwind CSS, and CVA.

See CHANGELOG.md for release history.

Install

pnpm add @vllnt/ui

Peer Dependencies

Required:

pnpm add react react-dom tailwindcss

Optional (only if using ThemeProvider, NavbarSaas, or other Next.js-specific components):

pnpm add next next-themes

Setup

1. Tailwind Preset

The library provides a Tailwind preset that includes all required theme colors, animations, and utilities.

// tailwind.config.ts
import uiPreset from "@vllnt/ui/tailwind-preset";

export default {
  presets: [uiPreset],
  content: [
    "./src/**/*.{ts,tsx}",
    // The preset auto-includes @vllnt/ui content paths
  ],
};

The preset configures:

• Colors: primary, secondary, muted, accent, destructive, background, foreground, card, popover, border, input, ring — all as hsl(var(--name)) for theming
• Border radius: lg, md, sm via --radius CSS variable
• Animations: accordion-down, accordion-up, shimmer
• Font: mono family via --font-mono variable
• Dark mode: class-based (darkMode: ["class"])
• Plugin: tailwindcss-animate

2. Import Styles

// app/layout.tsx or your main entry
import "@vllnt/ui/styles.css";

This imports Tailwind base/components/utilities + default theme variables + safe-area utilities.

3. Use Components

import { Button, Card, Badge } from "@vllnt/ui";

export function Example() {
  return (
    <Card>
      <Badge variant="secondary">New</Badge>
      <Button variant="default">Click me</Button>
    </Card>
  );
}

Exports

Theming

All colors use HSL CSS variables. Override them after importing styles:

/* Light theme */
:root {
  --background: 0 0% 100%;
  --foreground: 0 0% 3.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 0 0% 98%;
  --border: 214.3 31.8% 91.4%;
  --input: 214.3 31.8% 91.4%;
  --ring: 222.2 84% 4.9%;
  --radius: 0.5rem;
  --card: 0 0% 100%;
  --card-foreground: 0 0% 3.9%;
  --popover: 0 0% 100%;
  --popover-foreground: 0 0% 3.9%;
}

/* Dark theme (applied via class="dark" on html/body) */
.dark {
  --background: 0 0% 3.9%;
  --foreground: 0 0% 98%;
  /* ... override other variables */
}

Use @vllnt/ui/themes/default.css instead of @vllnt/ui/styles.css if you only want the variables without Tailwind base layer styles.

Component Patterns

All components follow these conventions:

• React.forwardRef — every component forwards refs
• React.ComponentPropsWithoutRef — extends native HTML element props
• cn() utility — merges Tailwind classes via clsx + tailwind-merge
• CVA variants — variant props defined with class-variance-authority
• Radix primitives — accessible behavior (focus, keyboard, ARIA) via Radix UI
• Slot support — asChild prop via @radix-ui/react-slot for render delegation

Variant Pattern

import { Button } from "@vllnt/ui";

// Button variants: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link"
// Button sizes: "default" | "sm" | "lg" | "icon"
<Button variant="outline" size="sm">Small Outline</Button>

Composition Pattern

import {
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogDescription,
} from "@vllnt/ui";

<Dialog>
  <DialogTrigger asChild>
    <Button>Open</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Title</DialogTitle>
      <DialogDescription>Description</DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>

Components

Form Controls

Layout

Feedback & Overlays

Navigation

Data Display

App Components

Content & Tutorial

AI

Financial

Ops / Status

Billing & Plans

Animation

Form Additions

Data & Metrics

App Shell (extended)

Utilities

import { cn } from "@vllnt/ui";

// Merge Tailwind classes (clsx + tailwind-merge)
<div className={cn("p-4 bg-primary", isActive && "bg-accent", className)} />

import { useDebounce } from "@vllnt/ui";

const debouncedValue = useDebounce(searchTerm, 300);

Types

import type {
  Content,
  ContentMeta,
  ContentProgress,
  ContentSection,
  DifficultyLevel,
  UISupportedLanguage,
} from "@vllnt/ui";

Requirements

• React >= 18.0.0
• Tailwind CSS >= 3.0.0
• Next.js >= 14.0.0 (optional — only for ThemeProvider, NavbarSaas, LangProvider)
• next-themes >= 0.4.0 (optional — only for ThemeProvider, ThemeToggle)

License

MIT