Components

Complete reference for all kuzan components

Layout Components

AppShell

Container for the entire application layout.

<script>
  import AppShell from '@kuratchi/kuzan/app-shell.html';
</script>

<AppShell>
  <!-- Your app content -->
</AppShell>

AppHeader

Sticky header bar for application navigation.

<script>
  import AppHeader from '@kuratchi/kuzan/app-header.html';
</script>

<AppHeader>
  <a href="/">My App</a>
  <nav>
    <a href="/dashboard">Dashboard</a>
    <a href="/settings">Settings</a>
  </nav>
</AppHeader>

Collapsible sidebar navigation.

<script>
  import Sidebar from '@kuratchi/kuzan/sidebar.html';
  import SidebarHeader from '@kuratchi/kuzan/sidebar-header.html';
  import SidebarContent from '@kuratchi/kuzan/sidebar-content.html';
  import SidebarMenu from '@kuratchi/kuzan/sidebar-menu.html';
  import SidebarMenuItem from '@kuratchi/kuzan/sidebar-menu-item.html';
</script>

<Sidebar>
  <SidebarHeader>
    <h2>Navigation</h2>
  </SidebarHeader>
  <SidebarContent>
    <SidebarMenu>
      <SidebarMenuItem href="/" icon="🏠">Home</SidebarMenuItem>
      <SidebarMenuItem href="/settings" icon="⚙️">Settings</SidebarMenuItem>
    </SidebarMenu>
  </SidebarContent>
</Sidebar>

Props:

data_side — 'left' | 'right' (default: 'left')
data_variant — 'sidebar' | 'floating' | 'inset'
data_collapsible — 'offcanvas' | 'icon' | 'none'

Dashboard

Pre-built dashboard layout with sidebar.

<script>
  import Dashboard from '@kuratchi/kuzan/dashboard.html';
  import DashboardContent from '@kuratchi/kuzan/dashboard-content.html';
</script>

<Dashboard>
  <DashboardContent>
    <h1>Dashboard</h1>
  </DashboardContent>
</Dashboard>

Content Components

Card

Bordered container for content sections.

<script>
  import Card from '@kuratchi/kuzan/card.koze';
</script>

<Card title="Card Title">
  <p>Card content goes here.</p>
</Card>

Props:

title — Card heading
bodyClass — Custom class for card body
data_compact — Reduced padding
data_side — Horizontal layout with image
data_variant — 'danger' | 'warning' (adds colored left border)

InfoCard

Card with icon and description.

<script>
  import InfoCard from '@kuratchi/kuzan/info-card.html';
</script>

<InfoCard title="Total Users" value="1,234" icon="👥" />

Props:

title — Card title
value — Main value to display
icon — Icon or emoji

MetricCard

Card for displaying key metrics.

<script>
  import MetricCard from '@kuratchi/kuzan/metric-card.html';
</script>

<MetricCard label="Revenue" value="$12,345" subvalue="+12% from last month" />

Props:

label — Metric label
value — Primary metric value
subvalue — Secondary description

StatsCard

Card with icon, value, and trend indicator.

<script>
  import StatsCard from '@kuratchi/kuzan/stats-card.html';
</script>

<StatsCard 
  label="Active Users" 
  value="2,543" 
  description="Currently online"
  icon="👤"
  trend="+12%"
  trendLabel="vs last week"
/>

Props:

label — Stat label
value — Primary value
description — Additional context
icon — Icon or emoji
trend — Trend value (e.g., "+12%")
trendLabel — Trend description

Alert

Contextual alert messages.

<script>
  import Alert from '@kuratchi/kuzan/alert.html';
</script>

<Alert data_variant="info">
  This is an informational message.
</Alert>

<Alert data_variant="danger" dismissible>
  This is a dismissible error alert.
</Alert>

Props:

data_variant — 'info' | 'success' | 'warning' | 'danger' | 'destructive' | 'error'
dismissible — Show close button

Callout

Highlighted content block with optional icon.

<script>
  import Callout from '@kuratchi/kuzan/callout.html';
</script>

<Callout title="Note" data_variant="info">
  This is important information.
</Callout>

Props:

title — Callout heading
data_variant — 'info' | 'success' | 'warning' | 'danger'

EmptyState

Placeholder for empty lists or missing content.

<script>
  import EmptyState from '@kuratchi/kuzan/empty-state.html';
</script>

<EmptyState 
  title="No items found" 
  description="Try adjusting your filters"
>
  <button data-variant="primary">Create Item</button>
</EmptyState>

Props:

title — Empty state title
description — Additional context

Hierarchical navigation trail.

<script>
  import Breadcrumb from '@kuratchi/kuzan/breadcrumb.html';
  import BreadcrumbItem from '@kuratchi/kuzan/breadcrumb-item.html';
</script>

<Breadcrumb>
  <BreadcrumbItem href="/">Home</BreadcrumbItem>
  <BreadcrumbItem href="/products">Products</BreadcrumbItem>
  <BreadcrumbItem>Current Page</BreadcrumbItem>
</Breadcrumb>

TabNav

Tabbed navigation interface.

<script>
  import TabNav from '@kuratchi/kuzan/tab-nav.html';
</script>

<TabNav 
  tabs={[
    { label: 'Overview', href: '/overview', active: true },
    { label: 'Settings', href: '/settings' },
    { label: 'Billing', href: '/billing' }
  ]}
/>

Props:

tabs — Array of { label, href, active? } objects

Dropdown menu with trigger button.

<script>
  import Dropdown from '@kuratchi/kuzan/dropdown.html';
</script>

<Dropdown label="Actions">
  <a href="/edit">Edit</a>
  <a href="/delete">Delete</a>
</Dropdown>

Props:

label — Dropdown trigger text

Data Display Components

Badge

Small status or label indicator.

<script>
  import Badge from '@kuratchi/kuzan/badge.html';
</script>

<Badge>Default</Badge>
<Badge data_variant="success">Active</Badge>
<Badge data_variant="danger">Error</Badge>
<Badge data_variant="warning">Pending</Badge>

Props:

data_variant — 'secondary' | 'outline' | 'destructive' | 'danger' | 'success' | 'warning' | 'info'

StatusChip

Status indicator with color-coded variants.

<script>
  import StatusChip from '@kuratchi/kuzan/status-chip.html';
</script>

<StatusChip status="active">Active</StatusChip>
<StatusChip status="pending">Pending</StatusChip>
<StatusChip status="error">Error</StatusChip>

Props:

status — 'active' | 'pending' | 'error' | 'success' | 'warning'

DataList

Vertical list of data items.

<script>
  import DataList from '@kuratchi/kuzan/data-list.html';
  import DataItem from '@kuratchi/kuzan/data-item.html';
</script>

<DataList>
  <DataItem label="Name" value="John Doe" />
  <DataItem label="Email" value="john@example.com" />
  <DataItem label="Role" value="Admin" />
</DataList>

Progress

Progress bar indicator.

<script>
  import Progress from '@kuratchi/kuzan/progress.html';
</script>

<Progress value={75} max={100} />

Props:

value — Current progress value
max — Maximum value (default: 100)
data_variant — 'primary' | 'success' | 'warning' | 'danger'

Interactive Components

Dialog

Modal dialog overlay.

<script>
  import Dialog from '@kuratchi/kuzan/dialog.html';
</script>

<Dialog title="Confirm Action">
  <p>Are you sure you want to proceed?</p>
  <div data-card="actions">
    <button data-variant="ghost">Cancel</button>
    <button data-variant="primary">Confirm</button>
  </div>
</Dialog>

Props:

title — Dialog heading

Drawer

Slide-out panel.

<script>
  import Drawer from '@kuratchi/kuzan/drawer.html';
</script>

<Drawer title="Settings" data_side="right">
  <p>Drawer content</p>
</Drawer>

Props:

title — Drawer heading
data_side — 'left' | 'right' (default: 'right')

Accordion

Collapsible content sections.

<script>
  import Accordion from '@kuratchi/kuzan/accordion.koze';
  import AccordionItem from '@kuratchi/kuzan/accordion-item.koze';
</script>

<Accordion>
  <AccordionItem title="Section 1">
    Content for section 1
  </AccordionItem>
  <AccordionItem title="Section 2">
    Content for section 2
  </AccordionItem>
</Accordion>

ThemeToggle

Button to switch between light and dark themes.

<script>
  import ThemeToggle from '@kuratchi/kuzan/theme-toggle.html';
</script>

<ThemeToggle />

Automatically:

Toggles .dark class on <html>
Persists choice to localStorage
Syncs all toggle instances

Utility Components

Loading

Loading spinner indicator.

<script>
  import Loading from '@kuratchi/kuzan/loading.html';
</script>

<Loading />
<Loading data_size="lg" />

Props:

data_size — 'sm' | 'md' | 'lg'

Hover tooltip (CSS-only).

<script>
  import Tooltip from '@kuratchi/kuzan/tooltip.html';
</script>

<Tooltip text="Helpful information">
  <button>Hover me</button>
</Tooltip>

Props:

text — Tooltip content

Hint

Inline help text or hint.

<script>
  import Hint from '@kuratchi/kuzan/hint.html';
</script>

<Hint>This field is required</Hint>
<Hint data_variant="error">Invalid input</Hint>

Props:

data_variant — 'default' | 'error' | 'success'

ThemeInit

Script to initialize theme from localStorage (prevents FOUC).

<script>
  import ThemeInit from '@kuratchi/kuzan/theme-init.html';
</script>

<head>
  <ThemeInit />
  <link rel="stylesheet" href="/node_modules/kuzan/src/styles/theme.css" />
</head>

Place in <head> before stylesheets.

Form Components

kuzan styles native HTML form elements via semantic selectors. No component imports needed:

<form>
  <label>
    Email
    <input type="email" placeholder="you@example.com" />
  </label>

  <label>
    Password
    <input type="password" />
  </label>

  <button type="submit">Sign In</button>
</form>

Styled elements:

<input> — Text, email, password, number, search, tel, url
<textarea> — Multi-line text input
<select> — Dropdown select
<button> — Buttons with variants via data-variant
<label> — Form labels

Button variants

Use data-variant attribute:

<button data-variant="primary">Primary</button>
<button data-variant="secondary">Secondary</button>
<button data-variant="ghost">Ghost</button>
<button data-variant="outline">Outline</button>
<button data-variant="link">Link</button>
<button data-variant="destructive">Destructive</button>

Button sizes

Use data-size attribute:

<button data-size="sm">Small</button>
<button>Default</button>
<button data-size="lg">Large</button>
<button data-size="icon">🔍</button>

Full-width button

Use data-block attribute:

<button data-block>Full Width</button>

Semantic HTML Styling

Many HTML elements are styled automatically without component imports:

Main content area

<main>
  <h1>Page Title</h1>
  <p>Content goes here.</p>
</main>

Automatically gets max-width, padding, and centering.

<main>
  <header>
    <h1>Dashboard</h1>
    <p>Welcome back</p>
  </header>
</main>

Styled with flex layout and spacing.

Section (card-like container)

<section>
  <article>
    <a href="/item-1">
      <strong>Item 1</strong>
      <small>Description</small>
    </a>
  </article>
  <article>
    <a href="/item-2">
      <strong>Item 2</strong>
      <small>Description</small>
    </a>
  </article>
</section>

Sections get borders and rounded corners. Articles are rows with dividers.

<nav>
  <a href="/">Home</a>
  <a href="/about">About</a>
  <a href="/contact">Contact</a>
</nav>

Horizontal navigation with hover states.

Component Composition

Components can be nested and combined:

<script>
  import Card from '@kuratchi/kuzan/card.koze';
  import Badge from '@kuratchi/kuzan/badge.html';
  import Alert from '@kuratchi/kuzan/alert.html';
</script>

<Alert data_variant="info">
  New features available!
</Alert>

<Card title="User Profile">
  <p>John Doe <Badge data_variant="success">Active</Badge></p>
  <p>Email: john@example.com</p>
  
  <div data-card="actions">
    <button data-variant="ghost">Cancel</button>
    <button data-variant="primary">Save</button>
  </div>
</Card>

Custom Classes

All components accept a class prop for custom styling:

<Card class="max-w-md mx-auto shadow-lg">
  Custom styled card
</Card>

<Badge class="uppercase tracking-wide">
  Custom badge
</Badge>

Next Steps

Theming — Customize colors and design tokens
Getting Started — Installation and setup guide

Components

Layout Components

AppShell

AppHeader

Sidebar

Dashboard

Content Components

Card

InfoCard

MetricCard

StatsCard

Alert

Callout

EmptyState

Navigation Components

Breadcrumb

TabNav

Dropdown

Data Display Components

Badge

StatusChip

DataList

Progress

Interactive Components

Dialog

Drawer

Accordion

ThemeToggle

Utility Components

Loading

Tooltip

Hint

ThemeInit

Form Components

Button variants

Button sizes

Full-width button

Semantic HTML Styling

Main content area

Page header

Section (card-like container)

Navigation

Component Composition

Custom Classes

Next Steps