mini-lit

Lightweight Lit components with shadcn-inspired theming, Tailwind CSS v4 styling, and Lucide icons.

View Live Demo & Interactive Documentation →
Explore all components with live examples, copy-paste code snippets, and interactive playgrounds.

Features

- Two Types of Components: Functional components for stateless UI elements (Button, Card, Badge) and Custom elements for components with internal state (theme-toggle, language-selector)
- shadcn/ui Themes: Compatible with shadcn/ui design system. Built-in default and Claude themes. Dark mode support via dark class
- TypeScript First: Full TypeScript support with type definitions. IDE autocomplete for all components and i18n
- Tailwind CSS v4: Modern styling with the latest Tailwind features
- Lucide Icons: Complete icon set with tree-shaking support

Quick Start

$3

``bash
npm install lit @mariozechner/mini-lit
`

$3

#### Option A: Vite Plugin (Recommended)

`bash
npm install -D @tailwindcss/vite
`

`typescript
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
plugins: [tailwindcss()],
});
`

#### Option B: Tailwind CLI

`bash
npm install -D @tailwindcss/cli
`

`json
// package.json scripts
"scripts": {
"dev": "tailwindcss -i ./src/app.css -o ./dist/app.css --watch",
"build": "tailwindcss -i ./src/app.css -o ./dist/app.css --minify"
}
`

$3

`css
/ src/app.css /

/ Import theme (includes dark mode and utilities) /
@import "@mariozechner/mini-lit/styles/themes/default.css";

/ Tell Tailwind to scan mini-lit components /
@source "../node_modules/@mariozechner/mini-lit/dist";

/ Import Tailwind /
@import "tailwindcss";
`

$3

If you're using LitElement components with decorators (custom elements or your own components extending LitElement), you must configure TypeScript properly:

`json
// tsconfig.json
{
"compilerOptions": {
"experimentalDecorators": true,
"useDefineForClassFields": false // Critical for LitElement reactivity!
}
}
`

Note: useDefineForClassFields: false is essential for LitElement's @property() and @state() decorators to work correctly. Without this setting, reactive properties won't trigger updates properly.

$3

`typescript
import { html, render } from "lit";
import { Button } from "@mariozechner/mini-lit/dist/Button.js";
import { Card } from "@mariozechner/mini-lit/dist/Card.js";
import { icon } from "@mariozechner/mini-lit/dist/icons.js";
import "@mariozechner/mini-lit/dist/ThemeToggle.js";
import { Send } from "lucide";
import "./app.css";

const App = () => html

render(App(), document.body);
`

Components

$3

- Buttons - All button variants and states
- Copy Button - Copy text to clipboard
- Download Button - Download files

$3

- Cards - Content containers with header, content, and footer sections
- Separators - Visual dividers
- Split Panel - Resizable layouts
- Dialogs - Modal dialogs

$3

- Inputs - Text, email, password inputs
- Textareas - Multi-line text input
- Selects - Dropdown selections
- Checkboxes - Boolean selections
- Switches - Toggle controls
- Labels - Form labels

$3

- Badges - Status indicators
- Alerts - Important messages with variants
- Progress - Progress indicators

$3

- Code Block - Syntax highlighted code with copy functionality
- Markdown - Rendered markdown with KaTeX math support
- Diff Viewer - Code difference viewer

$3

- Theme Toggle - Dark/light mode switcher
- Language Selector - i18n language switcher
- icon() - Render Lucide icons with size variants
- i18n() - Internationalization support

Component Types

$3

Stateless components that return TemplateResult:

`typescript
import { Button, Card, Badge } from "@mariozechner/mini-lit";

// Use directly in templates
${Button({ variant: "primary", children: "Click me" })}
${Badge({ children: "New" })}
`

$3

Stateful components that extend LitElement:

`typescript
// Custom elements are automatically registered when using the main import
import "@mariozechner/mini-lit";

// Use as HTML tags


`

Tree-Shaking & Bundle Optimization

IMPORTANT: The root index (@mariozechner/mini-lit) now only exports core utilities (component system, i18n, and icons). Individual components are not exported from the root to encourage optimal tree-shaking.

$3

`typescript
// ✅ Optimal - only includes what you use (~50-100KB)
import { Button } from "@mariozechner/mini-lit/dist/Button.js";
import { Card } from "@mariozechner/mini-lit/dist/Card.js";
import { icon } from "@mariozechner/mini-lit/dist/icons.js";
import "@mariozechner/mini-lit/dist/ThemeToggle.js";

// ⚠️ Root index only exports core utilities (NOT components)
import { i18n, setTranslations, createComponent } from "@mariozechner/mini-lit";
`

What's exported from the root index:
- Component system: ComponentLitBase, createComponent, defineComponent, styleComponent, and related types
- i18n system: i18n, setTranslations, setLanguage, getCurrentLanguage, defaultEnglish, defaultGerman
- Icons: icon function and related utilities

Available component paths:
- Functional components: /dist/Button.js, /dist/Card.js, /dist/Input.js, /dist/Select.js, /dist/Checkbox.js, etc.
- Custom elements: /dist/ThemeToggle.js, /dist/CodeBlock.js, /dist/MarkdownBlock.js, /dist/LanguageSelector.js, etc.
- Core utilities: /dist/mini.js (fc, createState, refs)

Bundle Size:
- Direct imports: ~50-100KB (only what you use)
- Importing all components: ~400KB+ (if you manually import everything)

Themes

mini-lit uses shadcn/ui compatible themes with CSS custom properties for colors, borders, and shadows.

$3

- default - Clean, modern theme
- claude - Claude-inspired theme

Switch themes by importing a different CSS file:

`css
@import "@mariozechner/mini-lit/styles/themes/claude.css";
`

$3

Toggle dark mode via the dark class:

`javascript
document.documentElement.classList.toggle("dark");
`

Or use the built-in component.

$3

For custom themes and theme generators:

- shadcn/ui themes
- Tweakcn theme generator

Internationalization

$3

`typescript
declare module "@mariozechner/mini-lit" {
interface i18nMessages extends MiniLitRequiredMessages {
Welcome: string;
Settings: string;
cartItems: (count: number) => string;
greeting: (name: string, time: string) => string;
}
}
`

$3

`typescript
import { setTranslations, defaultEnglish, defaultGerman } from "@mariozechner/mini-lit";

const translations = {
en: {
...defaultEnglish, // Includes required messages like "Copy", "Copied!"
Welcome: "Welcome",
Settings: "Settings",
cartItems: (count: number) =>
count === 0 ? "Your cart is empty" : count === 1 ? "1 item in your cart" : ${count} items in your cart,
greeting: (name: string, time: string) => Good ${time}, ${name}!,
},
de: {
...defaultGerman, // Includes required messages like "Kopieren", "Kopiert!"
Welcome: "Willkommen",
Settings: "Einstellungen",
cartItems: (count: number) =>
count === 0
? "Ihr Warenkorb ist leer"
: count === 1
? "1 Artikel im Warenkorb"
: ${count} Artikel im Warenkorb,
greeting: (name: string, time: string) => Guten ${time}, ${name}!,
},
};

setTranslations(translations);
`

$3

`typescript
import { i18n, getCurrentLanguage, setLanguage } from "@mariozechner/mini-lit";

// Simple strings
${i18n("Welcome")}
${i18n("Settings")}

// Functions with parameters
${i18n("cartItems")(3)} // "3 items in your cart"
${i18n("greeting")("Alice", "morning")} // "Good morning, Alice!"

// Language management
getCurrentLanguage() // "en" or "de"
setLanguage("de") // switches to German, reloads page

// Add language selector to UI

`

Development

The mini-lit repository includes both the component library and a comprehensive example gallery showcasing all components.

$3

`bash


Clone the repository

`bash
npm run dev
`

This command orchestrates:

1. TypeScript compilation of the mini-lit library (watching for changes in /src, outputting to /dist)
2. Vite dev server for the example gallery (in /example), automatically picking up the latest mini-lit builds

Open the URL displayed by Vite (typically http://localhost:5173) to view the example gallery. Any changes to either the mini-lit source code or the example application will trigger automatic rebuilds and browser updates through HMR.

$3

`
mini-lit/
├── src/ # mini-lit component library source
├── dist/ # Compiled library output
├── styles/ # Theme CSS files
├── example/ # Interactive component gallery
│ └── src/
│ └── pages/ # Individual component demos
└── package.json # Library package configuration
`

$3

Run formatting and linting checks for both the library and example:

`bash
npm run check
`

This command:

- Formats all code with Prettier
- Lints with Biome for code quality and style consistency
- Type-checks both the library and example with TypeScript
- Automatically runs on git commit via Husky pre-commit hooks

$3

`bash


Build the library

`bash


Build and publish the library to npm

`bash


Quick sync (when only source files changed)

The sync command builds and syncs files without restarting services, while deploy also restarts the Docker containers on the server.

Examples

See the /example` directory for a complete working example with all components, or visit the live demo.

Resources

- npm Package
- GitHub Repository
- Live Demo
- Lit Documentation
- Tailwind CSS v4

License

MIT