@kupola/components

48+ accessible, responsive UI components for building modern web interfaces.

Install

npm install @kupola/components

Peer dependency: @kupola/core ^3.0.0

Quick Start

import { Modal, Button, Alert } from '@kupola/components';

// Create a modal
const modal = Modal({
  title: 'Hello',
  closable: true,
}, html`<p>Modal content</p>`);

// Open modal
modal.open();

// Show alert
Alert.success('Operation successful');

Components

Layout

• Grid - Responsive grid system
• Divider - Visual separator
• StatCard - Statistics card
• Badge - Count badge
• Panel - Surface container with optional title, header, and footer

Navigation

• Breadcrumb - Page navigation
• Menu - Navigation menu
• Tabs - Tab switching
• Pagination - Page pagination
• Tree - Tree structure

Forms

• Input - Text input
• Textarea - Multi-line input
• Select - Dropdown selection
• Checkbox - Checkbox group
• Radio - Radio group
• Switch - Toggle switch
• Slider - Range slider
• NumberInput - Number input
• DatePicker - Date picker
• TimePicker - Time picker
• ColorPicker - Color picker
• FileUpload - File upload
• DynamicTags - Editable tags

Feedback

• Alert - Alert message
• Message - Toast notification
• Notification - Notification box
• Spin - Loading spinner
• Skeleton - Placeholder

Overlay

• Modal - Modal dialog
• Drawer - Slide panel
• Dialog - Confirm dialog
• Tooltip - Hint bubble
• Dropdown - Dropdown menu
• Collapse - Accordion

Data

• Table - Data table
• Form - Form validation
• Validation - Form validation utilities
• Timeline - Timeline display
• Heatmap - Heatmap chart
• Empty - Empty state

SchemaForm — Declarative Form Builder

Build complex forms from a JSON schema. Supports text, number, email, password, textarea, date, time, select, checkbox, radio, switch, and switcher field types.

import { SchemaForm } from '@kupola/components/schema-form';

const schema = {
  fields: [
    { name: 'username', type: 'text', label: 'Username', required: true },
    { name: 'email', type: 'email', label: 'Email', required: true },
    { name: 'role', type: 'select', label: 'Role', options: [
      { value: 'admin', label: 'Admin' },
      { value: 'user', label: 'User' },
    ] },
    { name: 'active', type: 'switch', label: 'Active' },
  ],
};

const form = SchemaForm({
  schema,
  density: 'default',    // 'compact' | 'default' | 'spacious'
  variant: 'outlined',   // 'outlined' | 'filled' | 'underlined'
  onSubmit: (values) => console.log(values),
});

Advanced APIs: createFormScope, bindSchemaForm, registerFormField, getFormFieldRenderer, validateSchema, schemaSubmit, FormDensity, FormVariant.

Overlay Management

Centralized overlay (modal/dialog/drawer) instance management.

import { createOverlay, createOverlayPlugin, useOverlay } from '@kupola/components/overlay';

// Create overlay service
const overlay = createOverlay();

// Open a modal
const modal = overlay.openModal({
  title: 'Confirm',
  content: 'Are you sure?',
  onConfirm: () => console.log('Confirmed'),
});

// Use as a plugin
const app = createApp(AppRoot);
app.use(createOverlayPlugin(overlay));

// In components
const { openModal, openDrawer } = useOverlay();

Declarative Views

TableView and FormView provide declarative, data-driven wrappers for the Table and Form components.

import { TableView, FormView } from '@kupola/components/views';

const userTable = TableView({
  ariaLabel: 'Users',
  columns: [
    { key: 'name', title: 'Name', sortable: true },
    { key: 'email', title: 'Email' },
    { key: 'role', title: 'Role', render: (role) => `<span class="badge">${role}</span>` },
  ],
  data: users,
  options: { rowKey: 'id', showPagination: true, pageSize: 20 },
});

Media

• Avatar - User avatar
• Carousel - Image carousel
• ImagePreview - Image lightbox
• Progress - Progress bar
• Tag - Tag label

Tools

• Calendar - Calendar widget
• Countdown - Countdown timer
• Kbd - Keyboard key
• VirtualList - Virtual scrolling

Icons

import { Icons } from '@kupola/components/icons';

// Get SVG string
const svg = Icons.svg('user');

// Render all icons
Icons.render(document.body);

// Register custom icons
Icons.registerIcons({
  custom: '<path d="..."/>'
});

// Register icon groups
Icons.registerGroup('navigation', {
  'arrow-up': '<path d="..."/>',
  'arrow-down': '<path d="..."/>',
});
Icons.registerAllGroups();

// Register an icon provider
import { registerIconProvider, createKupolaIconProvider, createIconComponent, setupIconResolver } from '@kupola/components/icons';

registerIconProvider('lucide', createKupolaIconProvider({
  resolve: (name) => lucideIcons[name],
}));

// Create a custom icon component
const MyIcon = createIconComponent('my-icon');

// Set up icon resolution
setupIconResolver((name) => customIconMap[name]);

// Available icon groups
import { iconGroups } from '@kupola/components/icons';
console.log(iconGroups);

// SVG path constants
import { PATHS } from '@kupola/components/icons';

Custom Icon Replacement

Kupola components use built-in icons, but you can replace them globally using registerIcons:

import { registerIcons } from '@kupola/components/icon-config';

registerIcons({
  'x': '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>',
  'chevron-down': '<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="6 9 12 15 18 9"/></svg>',
  'check-circle': '<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="20 6 9 17 4 12"/></svg>',
});

Available icon names for replacement:

• x - Close icon (Modal, Drawer)
• chevron-left - Left arrow (Carousel, Datepicker, Pagination, ImagePreview)
• chevron-right - Right arrow (Carousel, Datepicker, Pagination, ImagePreview)
• chevron-down - Down arrow (Dropdown, Select, Collapse)
• check-circle - Success icon (Dialog, Message, Notification)
• alert-triangle - Warning icon (Dialog, Message, Notification)
• x-circle - Error icon (Dialog, Message, Notification)
• info-circle - Info icon (Dialog, Message, Notification)
• calendar - Calendar icon (Datepicker)
• clock - Clock icon (Timepicker)
• plus - Plus icon (DynamicTags)
• upload - Upload icon (FileUpload)
• table - Table icon (Empty)

Third-Party Icon Integration

Kupola supports integration with any third-party icon library. Here are examples:

Lucide Icons:

import { registerIcons } from '@kupola/components/icon-config';
import { X, ChevronDown, CheckCircle } from 'lucide-static';

registerIcons({
  'x': X,
  'chevron-down': ChevronDown,
  'check-circle': CheckCircle,
});

Heroicons:

import { registerIcons } from '@kupola/components/icon-config';
import { X, ChevronDown, CheckCircle } from '@heroicons/24-solid';

registerIcons({
  'x': X,
  'chevron-down': ChevronDown,
  'check-circle': CheckCircle,
});

Phosphor Icons:

import { registerIcons } from '@kupola/components/icon-config';
import { X, ChevronDown, CheckCircle } from 'phosphor-react';

registerIcons({
  'x': () => X({ size: 20, weight: 'bold' }).props.children,
  'chevron-down': () => ChevronDown({ size: 20, weight: 'bold' }).props.children,
});

Iconify:

import { registerIcons } from '@kupola/components/icon-config';
import { icon } from '@iconify/iconify';

registerIcons({
  'x': () => icon.renderHTML({ icon: 'mdi:close' }),
  'chevron-down': () => icon.renderHTML({ icon: 'mdi:chevron-down' }),
});

Font Awesome (SVG mode):

import { registerIcons } from '@kupola/components/icon-config';
import { X, ChevronDown, CheckCircle } from '@fortawesome/free-solid-svg-icons';
import { dom, svg } from '@fortawesome/fontawesome-svg-core';
dom.i2svg();

registerIcons({
  'x': () => svg(X).html[0],
  'chevron-down': () => svg(ChevronDown).html[0],
  'check-circle': () => svg(CheckCircle).html[0],
});

Font Awesome (Font mode):

import { registerIcons } from '@kupola/components/icon-config';
import { library } from '@fortawesome/fontawesome-svg-core';
import { X, ChevronDown, CheckCircle } from '@fortawesome/free-solid-svg-icons';
library.add(X, ChevronDown, CheckCircle);

registerIcons({
  'x': '<i class="fa-solid fa-xmark"></i>',
  'chevron-down': '<i class="fa-solid fa-chevron-down"></i>',
  'check-circle': '<i class="fa-solid fa-circle-check"></i>',
});

Material Symbols (Font mode):

<!-- Add CSS in HTML head -->
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:wght@400&display=swap">

import { registerIcons } from '@kupola/components/icon-config';

registerIcons({
  'x': { type: 'font', class: 'material-symbols-outlined' },
  'chevron-down': { type: 'font', class: 'material-symbols-outlined' },
  'check-circle': { type: 'font', class: 'material-symbols-outlined' },
});

Custom SVG Strings:

import { registerIcons } from '@kupola/components/icon-config';

registerIcons({
  'x': '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><line x1="18" y1="6" x2="6" y2="18"/></svg>',
});

CSS

Include the CSS file:

<link rel="stylesheet" href="node_modules/@kupola/components/dist/css/index.css">

Or import in JavaScript:

import '@kupola/components/css';

TypeScript

import type { ModalOptions, ButtonProps, SelectOptions } from '@kupola/components';

API Reference

See the documentation site for detailed API references.

License

MIT