ColorSnap UI — Documentation

Installation

Install ColorSnap UI via npm for React projects, or skip npm entirely and use the CDN for plain HTML.

# Install with npm
npm install colorsnap-ui

import { Button, Card, ColorSnapProvider } from 'colorsnap-ui';
import 'colorsnap-ui/styles';

function App() {
  return (
    <ColorSnapProvider theme="midnight">
      <Button>Hello ColorSnap</Button>
    </ColorSnapProvider>
  );
}

<!-- No npm required — see CDN Setup -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/colorsnap-ui/dist/cdn/colorsnap.css">
<script src="https://cdn.jsdelivr.net/npm/colorsnap-ui/dist/cdn/colorsnap.umd.js"></script>

Wrap your React app in ColorSnapProvider to enable global theming, toasts, and theme context for hooks.

Package	Description
colorsnap-ui	Main React component library
colorsnap-ui/styles	Global CSS variables and base styles
npx colorsnap-ui	CLI for copying components into your project

CDN Setup

No npm, no React, no build step. Add two lines to any HTML file and start using ColorSnap classes immediately.

// React apps should use npm — CDN is for static HTML
import 'colorsnap-ui/styles';

<!-- In <head> -->
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/colorsnap-ui/dist/cdn/colorsnap.css">

<!-- Before </body> -->
<script src="https://cdn.jsdelivr.net/npm/colorsnap-ui/dist/cdn/colorsnap.umd.js"></script>
<script>
  ColorSnap.setTheme('midnight');
</script>

CDN API

Method	Description
ColorSnap.setTheme(name)	Switch the global page theme
ColorSnap.toast(options)	Show a toast notification
data-cs-modal="#id"	Declarative modal trigger attribute

ThemeProvider

Wrap your React app with ColorSnapProvider to enable theme context, toasts, and consistent styling across all components.

import { ColorSnapProvider } from 'colorsnap-ui';

<ColorSnapProvider theme="midnight">
  <App />
</ColorSnapProvider>

CLI

The colorsnap-ui CLI copies components directly into your project so you own the source.

npx colorsnap-ui init
npx colorsnap-ui add button
npx colorsnap-ui theme cyberpunk
npx colorsnap-ui cdn --theme midnight
npx colorsnap-ui list

See cli.html for the full CLI reference.

Button

The primary interactive element. Supports multiple variants, sizes, loading state, and disabled state via React props or CDN classes.

Variants

Sizes

XS

SM

MD

LG

XL

import { Button } from 'colorsnap-ui';

<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="danger">Danger</Button>
<Button loading>Loading</Button>
<Button size="lg" className="cs-button--glow">Glow</Button>

<button class="cs-button">Primary</button>
<button class="cs-button cs-button--secondary">Secondary</button>
<button class="cs-button cs-button--ghost">Ghost</button>
<button class="cs-button cs-button--danger">Danger</button>
<button class="cs-button cs-button--outline">Outline</button>
<button class="cs-button cs-button--pill cs-button--glow">Glow Pill</button>
<button class="cs-button cs-button--loading">Loading</button>
<button class="cs-button" disabled>Disabled</button>

<!-- Sizes -->
<button class="cs-button cs-button--xs">XS</button>
<button class="cs-button cs-button--sm">SM</button>
<button class="cs-button cs-button--lg">LG</button>
<button class="cs-button cs-button--xl">XL</button>

Props

Prop	Type	Default	Description
variant	'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'outline'	'primary'	Visual style variant
size	'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'	'md'	Button size
loading	boolean	false	Show spinner and disable interaction
disabled	boolean	false	Disable the button
className	string	—	Additional CDN modifier classes
onClick	() => void	—	Click handler

CSS Classes

Class	Description
cs-button	Base button (required)
cs-button--secondary	Secondary/outlined variant
cs-button--ghost	Transparent ghost variant
cs-button--danger	Red destructive variant
cs-button--outline	Primary-colored outline
cs-button--xs / --sm / --lg / --xl	Size modifiers
cs-button--pill	Fully rounded pill shape
cs-button--block	Full width
cs-button--loading	Spinner state, disables clicks
cs-button--disabled	Disabled look (also use disabled attr)
cs-button--glow	Glowing shadow effect
cs-button--icon	Square icon-only button

Card

Surface container for grouping content. Available in default, elevated, glass, and bordered variants.

Default Card

Basic card content with theme-aware styling.

Elevated

Raised surface with drop shadow.

Glass

Glassmorphism blur effect.

import { Card } from 'colorsnap-ui';

<Card variant="elevated">
  <Card.Title>Card Title</Card.Title>
  <Card.Body>Content here.</Card.Body>
  <Card.Footer>
    <Button size="sm">Action</Button>
  </Card.Footer>
</Card>

<div class="cs-card cs-card--elevated">
  <h3 class="cs-card-title">Card Title</h3>
  <p class="cs-card-body">Content here.</p>
  <div class="cs-card-footer">
    <span class="cs-badge cs-badge--success">Active</span>
    <button class="cs-button cs-button--sm">Action</button>
  </div>
</div>

Class	Description
cs-card	Base card container
cs-card--elevated	Drop shadow elevation
cs-card--glass	Glassmorphism blur
cs-card--bordered	Stronger border
cs-card--hover	Lift on hover
cs-card-title	Card heading
cs-card-body	Card body text
cs-card-footer	Footer row

Input

Form inputs, textareas, and selects with built-in label, hint, and error state support.

Email

We'll never share your email.

This field is required.

import { Input, Textarea, Select } from 'colorsnap-ui';

<Input label="Email" type="email" required hint="We'll never share your email." />
<Input error="This field is required." />
<Textarea placeholder="Message…" />
<Select options={['Option 1', 'Option 2']} />

<div class="cs-form-group">
  <label class="cs-label cs-label--required">Email</label>
  <input class="cs-input" type="email" placeholder="you@example.com" />
  <p class="cs-form-hint">We'll never share your email.</p>
</div>

<input class="cs-input cs-input--error" placeholder="Error state" />
<p class="cs-form-error">This field is required.</p>

Class	Description
cs-input	Text input field
cs-input--error	Error state styling
cs-textarea	Multi-line text area
cs-select	Styled select dropdown
cs-label	Form label
cs-label--required	Required field indicator
cs-form-group	Label + input wrapper
cs-form-hint	Helper text below input
cs-form-error	Error message text

Badge

Small labels for status indicators, counts, and tags.

Default Success Warning Danger Info With dot

import { Badge } from 'colorsnap-ui';

<Badge>Default</Badge>
<Badge variant="success">Success</Badge>
<Badge variant="warning" dot>With dot</Badge>

<span class="cs-badge">Default</span>
<span class="cs-badge cs-badge--success">Success</span>
<span class="cs-badge cs-badge--warning">Warning</span>
<span class="cs-badge cs-badge--danger">Danger</span>
<span class="cs-badge cs-badge--info">Info</span>
<span class="cs-badge cs-badge--dot cs-badge--success">With dot</span>

Class	Description
cs-badge	Base badge
cs-badge--success	Green success badge
cs-badge--warning	Yellow warning badge
cs-badge--danger	Red danger badge
cs-badge--info	Blue info badge
cs-badge--dot	Pulsing dot indicator

Avatar

User avatars with image or initials fallback. Supports sizes, ring border, and stacked groups.

JD

AK

MR

XL

A

B

C

+3

import { Avatar, AvatarGroup } from 'colorsnap-ui';

<Avatar initials="JD" size="lg" />
<Avatar src="/user.jpg" alt="Jane" />
<AvatarGroup max={3}>…</AvatarGroup>

<div class="cs-avatar">JD</div>
<img class="cs-avatar" src="/user.jpg" alt="Jane" />

<div class="cs-avatar-group">
  <div class="cs-avatar cs-avatar--sm">A</div>
  <div class="cs-avatar cs-avatar--sm">B</div>
  <div class="cs-avatar cs-avatar--sm">+3</div>
</div>

Class	Description
cs-avatar	Base avatar circle
cs-avatar--sm / --lg	Size variants
cs-avatar--ring	Primary ring border
cs-avatar-group	Overlapping avatar stack

Alert

Inline alerts for info, success, warning, and error states.

Info: This is an informational message.

Success: Your changes were saved.

Warning: Trial expires in 3 days.

Error: Something went wrong.

import { Alert } from 'colorsnap-ui';

<Alert variant="info">Informational message</Alert>
<Alert variant="success">Changes saved!</Alert>
<Alert variant="warning">Trial expires soon.</Alert>
<Alert variant="danger">Something went wrong.</Alert>

<div class="cs-alert cs-alert--info">Informational message</div>
<div class="cs-alert cs-alert--success">Changes saved!</div>
<div class="cs-alert cs-alert--warning">Trial expires soon.</div>
<div class="cs-alert cs-alert--danger">Something went wrong.</div>

Class	Description
cs-alert	Base alert container
cs-alert--info	Blue informational alert
cs-alert--success	Green success alert
cs-alert--warning	Yellow warning alert
cs-alert--danger	Red error alert

Progress

Progress bars for loading states and completion tracking. Set the fill width via a modifier class or inline width on the bar element.

import { Progress } from 'colorsnap-ui';

<Progress value={65} variant="success" size="lg" />
<Progress value={85} variant="warning" />

<div class="cs-progress">
  <div class="cs-progress-bar" style="width: 65%"></div>
</div>

<div class="cs-progress cs-progress--lg">
  <div class="cs-progress-bar cs-progress--success" style="width: 80%"></div>
</div>

Class	Description
cs-progress	Progress track container
cs-progress--lg	Taller progress bar
cs-progress-bar	Fill element (set width)
cs-progress--success	Green fill color
cs-progress--warning	Yellow fill color
cs-progress--danger	Red fill color

Modal

Dialog overlay triggered declaratively with data-cs-modal.

Full Modal documentation coming soon. See the CDN Setup section for the data-cs-modal attribute.

Tabs

Tabbed content panels for organizing related views.

Full Tabs documentation coming soon.

Dropdown

Dropdown menus for actions and navigation.

Full Dropdown documentation coming soon.

Toast

Notification toasts via ColorSnap.toast() or the useToast hook.

Full Toast documentation coming soon.

Sidebar

Collapsible sidebar navigation component.

Full Sidebar documentation coming soon.

Table

Data tables with sorting and responsive layout.

Full Table documentation coming soon.

Accordion

Expandable content sections.

Full Accordion documentation coming soon.

DatePicker

Calendar date picker input.

Full DatePicker documentation coming soon.

Slider

Range slider input for numeric values.

Full Slider documentation coming soon.

Tooltip

Hover tooltips for contextual hints.

Full Tooltip documentation coming soon.

Breadcrumb

Navigation breadcrumb trail.

Full Breadcrumb documentation coming soon.

Pagination

Page navigation controls.

Full Pagination documentation coming soon.

Themes Overview

52 built-in themes switchable with one line of JavaScript.

See themes.html for the full theme gallery.

Custom Themes

Create and register custom theme palettes.

Full Custom Themes documentation coming soon.

Dark Mode

Most ColorSnap themes are dark-first. Use ColorSnap.setTheme() to toggle.

Full Dark Mode documentation coming soon.

useTheme

React hook for reading and setting the active theme.

Full useTheme documentation coming soon.

useToast

React hook for triggering toast notifications.

Full useToast documentation coming soon.

useDebounce

Debounce a value with a configurable delay.

Full useDebounce documentation coming soon.

useLocalStorage

Persist state to localStorage with SSR-safe hydration.

Full useLocalStorage documentation coming soon.

cn

Utility for merging class names conditionally.

Full cn documentation coming soon.

format

Formatting helpers for dates, numbers, and strings.

Full format documentation coming soon.

validators

Common form validation helpers.

Full validators documentation coming soon.