@billy_mcdowell/shadcn-web-components

v0.2.1

Published

6 days ago

A professional web component library built with Lit, following shadcn design principles

Downloads

655

0High
0Medium
0Low

billy_mcdowell

web-components lit design-system shadcn ui-components

shadcn Web Components

A professional, enterprise-grade web component library built with Lit, following shadcn/ui design principles.

Storybook documentation · Production component gallery

Features

✨ Modern & Accessible: Built with Lit and WCAG 2.1 AA compliant
🎨 Beautiful Dark Theme: Carefully crafted oklch color palette
📦 Tree-Shakeable: Import only what you need
🔧 Customizable: Theme with CSS custom properties
📚 Well Documented: Interactive Storybook documentation
⚡ Lightweight: Core components < 8KB gzipped
🎯 Type-Safe: Full TypeScript support

Quick Start

Installation

npm install @billy_mcdowell/shadcn-web-components

If you use the Chart component, also install its peer dependency:

npm install chart.js

Load the default design tokens and optional reset in your document <head>:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@billy_mcdowell/shadcn-web-components@latest/dist/styles/tokens.css"
>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@billy_mcdowell/shadcn-web-components@latest/dist/styles/reset.css"
>

Then register components from your application entry point. With npm and a bundler, lit, @floating-ui/dom, focus-trap, and @lit/context are installed automatically and resolved for you — no import map is required.

Prefer subpath imports for the smallest bundle:

import '@billy_mcdowell/shadcn-web-components/button';

Importing the package root registers every component and is best reserved for demos or the production gallery.

Dependencies

| Components / subpaths | Required bare imports | |-----------------------|----------------------| | Most primitives (button, input, badge, etc.) | lit | | dialog, sheet, drawer, alert-dialog | lit, focus-trap, @lit/context | | popover | lit, @floating-ui/dom, @lit/context | | chart | lit, chart.js | | Root dist/index.js (all components) | all of the above |

npm / bundler: npm install @billy_mcdowell/shadcn-web-components pulls in lit, @floating-ui/dom, focus-trap, and @lit/context. Install chart.js separately when using ./chart.

CDN / plain HTML: add the matching entries to an import map before any module scripts (see CDN Usage below).

CDN Usage

For plain HTML without a build step, use the styles above followed by an import map and the exact published module:

<script type="importmap">
  {
    "imports": {
      "lit": "https://esm.sh/[email protected]",
      "lit/decorators.js": "https://esm.sh/[email protected]/decorators.js",
      "@floating-ui/dom": "https://esm.sh/@floating-ui/[email protected]",
      "focus-trap": "https://esm.sh/[email protected]",
      "@lit/context": "https://esm.sh/@lit/[email protected]",
      "chart.js": "https://esm.sh/[email protected]",
      "chart.js/": "https://esm.sh/[email protected]/"
    }
  }
</script>
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/@billy_mcdowell/shadcn-web-components@latest/dist/components/button/button.js"
></script>

For the full component gallery, include every import map entry above and load dist/index.js instead. For a single primitive such as button, only the lit entries are required.

The import map must appear before the module script. Use the direct dist files rather than a transformed +esm endpoint so registration side effects are preserved.

See every component running from this published package in the production component gallery.

Usage

Import individual components:

import '@billy_mcdowell/shadcn-web-components/button';

Or import all components (larger bundle — prefer subpaths in production apps):

import '@billy_mcdowell/shadcn-web-components';

Use in your HTML:

<shadcn-button variant="default">Click me</shadcn-button>
<shadcn-button variant="destructive">Delete</shadcn-button>
<shadcn-button variant="outline">Cancel</shadcn-button>

Components

See Component Status for the complete shadcn/ui catalog and implementation status.

Currently Available

Accordion
Alert
Alert Dialog
Aspect Ratio
Avatar
Badge
Breadcrumb
Button
Button Group
Calendar
Card
Carousel
Chart
Checkbox
Collapsible
Combobox
Command
Context Menu
Data Table
Date Picker
Dialog
Drawer
Dropdown Menu
Empty
Field
Hover Card
Input
Input OTP
Input Group
Item
Kbd
Label
Menubar
Native Select
Navigation Menu
Pagination
Popover
Progress
Radio Group
Resizable
Select
Separator
Sheet
Sidebar
Skeleton
Slider
Sonner
Spinner
Switch
Table
Tabs
Textarea
Toggle
Toggle Group
Tooltip
Typography

Implementation Status

Stable primitives: Button, Card, Input, Label, Separator, Skeleton, Spinner, Textarea, Kbd.
Interactive controls: Checkbox, Collapsible, Command, Hover Card, Input OTP, Radio Group, Select, Slider, Switch, Tabs, Toggle, Toggle Group, Tooltip.
Modal surfaces: Alert Dialog, Dialog, Drawer, Sheet.
Implemented, parity hardening in progress: Popover, Dropdown Menu, Context Menu, Menubar, Navigation Menu.

Import Paths

Import the full library:

import '@billy_mcdowell/shadcn-web-components';

Import individual components:

import '@billy_mcdowell/shadcn-web-components/button';
import '@billy_mcdowell/shadcn-web-components/dialog';
import '@billy_mcdowell/shadcn-web-components/popover';

Use the Lit style helpers when authoring your own Lit components:

import '@billy_mcdowell/shadcn-web-components/styles';

This JavaScript subpath exports Lit CSSResult helpers for component authors. It does not load the global design tokens; use the stylesheet links shown above for the default application theme.

Button Component

The button component supports multiple variants and sizes:

Variants

default - Primary button style
destructive - For dangerous actions
outline - Subtle bordered style
secondary - Muted background
ghost - Transparent background
link - Text link style

Sizes

sm - Small (36px height)
default - Default (40px height)
lg - Large (44px height)
icon - Square icon button (40x40px)

Examples

<!-- Variants -->
<shadcn-button variant="default">Save</shadcn-button>
<shadcn-button variant="destructive">Delete</shadcn-button>
<shadcn-button variant="outline">Cancel</shadcn-button>

<!-- Sizes -->
<shadcn-button size="sm">Small</shadcn-button>
<shadcn-button size="lg">Large</shadcn-button>

<!-- Icon Button -->
<shadcn-button size="icon">
  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
    <path d="M5 12h14M12 5l7 7-7 7"/>
  </svg>
</shadcn-button>

<!-- Disabled -->
<shadcn-button disabled>Disabled</shadcn-button>

<!-- With Event Listener -->
<shadcn-button id="myButton">Click me</shadcn-button>
<script>
  document.getElementById('myButton')
    .addEventListener('button-click', (e) => {
      console.log('Button clicked!', e.detail);
    });
</script>

Customization

All components can be themed using CSS custom properties:

shadcn-button {
  --button-bg: oklch(0.5 0.2 220);
  --button-color: oklch(1 0 0);
  --button-border: oklch(0.6 0.2 220);
}

Available CSS Custom Properties

Each component exposes CSS custom properties for theming. See the component documentation for details.

Development

Prerequisites

Node.js 18+
npm or pnpm

Setup

# Install dependencies
npm install

# Start Storybook
npm run storybook

# Build library
npm run build

# Type check
npm run type-check

# Generate component manifest
npm run analyze

Project Structure

shadcn-web-components/
├── src/
│   ├── components/          # Component implementations
│   │   └── button/
│   │       ├── button.ts
│   │       ├── button.stories.ts
│   │       └── index.ts
│   ├── styles/             # Design tokens
│   │   ├── tokens.css
│   │   ├── reset.css
│   │   └── index.ts
│   └── index.ts            # Main entry
├── .storybook/             # Storybook config
└── dist/                   # Build output

Design System

This library follows shadcn's design principles with a dark theme color palette using oklch color space for better perceived uniformity.

Color Tokens

--background, --foreground - Base colors
--primary, --secondary - Brand colors
--accent, --muted - Semantic colors
--destructive - Error/danger state
--border, --input - UI element colors

Typography Scale

--font-size-xs to --font-size-4xl

Spacing Scale

--spacing-1 (4px) to --spacing-12 (48px)

Border Radius

--radius-sm to --radius-full

Browser Support

Chrome/Edge 90+
Firefox 88+
Safari 15+

Resources

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Note: This library is currently in active development. The API may change before v1.0.0.