# Introduction

Mielui is a component library for Svelte 5 and Tailwind v4. It includes components, theme tokens, and a CLI for copying source into your project.

## Build with Mielui

Start with everyday controls, compose larger interfaces from named parts, and tune everything through one set of theme tokens. Each component page pairs a live preview with source examples and an API reference.

- [Native controls](/docs/components/native-controls): Buttons, text fields, and selects built around native form elements.
- [Inputs](/docs/components/inputs): Selection, numeric, file, and structured inputs.
- [Forms](/docs/components/forms): Labels, field groups, validation, and form composition.
- [Dates](/docs/components/dates): Calendars and date selection for single dates and ranges.
- [Navigation](/docs/components/navigation): Breadcrumbs, pagination, and tabbed views.
- [Overlays](/docs/components/overlays): Dialogs, menus, panels, and contextual information.
- [Layout](/docs/components/layout): Surfaces, disclosure, grouping, scrolling, and tabular layout.
- [Status and content](/docs/components/status-and-content): Status messages, progress, identity, and text.
- [Blocks](/docs/components/blocks): Larger parts built from the components: code, tables, toasts, toolbars, and more.
- [AI components](/docs/components/ai-components): Conversations, messages, tools, and the composer for chat and agent interfaces.
- [Chart components](/docs/components/chart-components): Charts, gauges, and heatmaps for showing data.
- [Actions](/docs/actions): 3 entries

## Choose how to use it

Both paths use the same components and theme system. Choose based on whether you want dependency updates or direct ownership of the implementation.

| Decision | Package import | CLI source copy |
| --- | --- | --- |
| Best fit | Use the library through its public API. | Adapt component internals for your product. |
| Source | Imported from `@mielui/svelte`. | Copied into your repository. |
| Customization | Compose parts, set props, and apply classes or tokens. | Use the same options, plus edit the source directly. |
| Updates | Upgrade the package dependency. | Review upstream changes alongside your local edits. |

Trying Mielui for the first time? Start with package imports. Choose source copy when you already know you need to change component behavior.

## Requirements

- Svelte 5.56 or newer, with or without SvelteKit
- Tailwind CSS v4
- pnpm, npm, Yarn, or Bun

Start with an existing Svelte app and import the Mielui stylesheet once at the application level.

## Quick start

Install the package:

~~~~sh
pnpm add @mielui/svelte
~~~~

Import the shared styles in your application stylesheet:

~~~~css
@import '@mielui/svelte/ui.css';
~~~~

Then use your first component:

~~~~svelte
<script>
  import { Button } from '@mielui/svelte';
</script>

<Button>Get started</Button>
~~~~

Prefer local source? Initialize the CLI and add a component instead:

~~~~sh
pnpm dlx @mielui/svelte init -y
pnpm dlx @mielui/svelte add button
~~~~

Follow [Installation](/docs/installation.md) for the local stylesheet import, component paths, and full setup for either approach.

## Make it your own

Set colors, typography, corners, spacing, and motion together in [Theme Studio](/studio). Preview the result on working components, then export CSS or JSON.

Compound components expose named parts such as Root, Trigger, and Content. Compose the parts shown on each component page, and use classes to adjust individual regions without replacing the whole component.

## Where to go next

- [Installation](/docs/installation.md): Set up package imports or the source-copy workflow.
- [Components](/docs/components.md): Explore live examples, supported props, and composition patterns.
- [Theming](/docs/theming.md): Apply a preset or connect theme tokens to your own design.
- [Agent skill](/docs/agent-skill.md): Give your coding agent Mielui-specific guidance for implementation.