# Introduction

Source: https://lumeo.nativ.sh/docs/introduction

Getting started

You can ship in about 60 seconds.

# Welcome to Lumeo.

A Blazor component library inspired by shadcn/ui — beautifully designed, accessible, and composable.

WASM Server .NET 10 568 KB core MIT

$ dotnet add package Lumeo

Core package (~568 KB). Add satellite packages for Charts, DataGrid, Editor, Scheduler, or Gantt as needed.

## What Lumeo is

Lumeo is a Blazor component library inspired by [shadcn/ui](https://ui.shadcn.com), bringing the same philosophy of beautifully designed, accessible, and composable components to the .NET ecosystem. Built on top of Tailwind CSS v4 and targeting .NET 10, Lumeo gives you a complete set of UI primitives that you own and control — no black-box overrides, no style collisions.

Every component is designed with accessibility and developer experience in mind. Components are fully themeable via CSS variables, work seamlessly in both light and dark mode, and expose a consistent parameter API so you can drop them into any Blazor Server or WebAssembly project.

## Design philosophy

Lumeo follows shadcn/ui's naming style rather than the prefixed approach you see in MudBlazor (`<MudCard>`) or Ant Design Blazor (`<AntCard>`). Components are unprefixed — `<Card>`, `<Dialog>`, `<Button>` — and the library uses C#'s `@namespace Lumeo` plus a global using to keep markup clean.

This reads like native HTML, matches the shadcn aesthetic the library is inspired by, and keeps your `.razor` files scannable. If a BCL type collides (e.g. `Text`, `Link`) you can always fully qualify with `Lumeo.Text` — the same pattern you'll see throughout these docs.

### Slot naming — the `Content` suffix

Because names are unprefixed, a `RenderFragment` slot named `Icon` would shadow the `<Icon>` component inside its own body. The convention is simple: when a slot name would collide with a component name, suffix the slot with `Content`.

Starting in v1.6.0, `Icon` and `Label` slots have been renamed to `IconContent` and `LabelContent` across ten components: `Alert`, `Badge`, `EmptyState`, `Rating`, `Result`, `Segmented`, `SidebarMenuButton`, `StepsItem`, `TabsTrigger`, and `TimelineItem`. The old names remain as `[Obsolete]` aliases — existing code keeps working with a compile-time warning, and the aliases are removed in 2.0.

Naming tip

Other slot names don't collide and stay as-is — `ChildContent`, `HeaderContent`, `EmptyContent`, `LoadingTemplate`, `TriggerContent`, `ToolbarContent`, `Actions`, `Extra`, `Leading`, `Trailing`, `Prefix`, `Suffix`, `LeftIcon`, and `RightIcon`.

## Installation

Install the NuGet package into your Blazor project:

1

### Add the packages

Lumeo 2.0 follows the DevExpress / Telerik / Microsoft.Extensions model: a small core package plus opt-in satellites for heavy components. The core stays at ~568 KB instead of ~918 KB — you only pay for what you use.

bash

\# Core — always required (~110 components)
$ dotnet add package Lumeo

\# Add satellites only for what you use:
$ dotnet add package Lumeo.Charts     \# Chart and 30+ subtypes
$ dotnet add package Lumeo.DataGrid   \# DataGrid, DataTable, Filter
$ dotnet add package Lumeo.Editor     \# RichTextEditor
$ dotnet add package Lumeo.Scheduler  \# Scheduler
$ dotnet add package Lumeo.Gantt      \# Gantt

Or reference them directly in your `.csproj`. All packages share one version (lockstep) — always upgrade them together:

**Since v3.7.0:** the DataGrid's Excel/PDF export backend (ClosedXML + QuestPDF, ~1.65 MB brotli) lives in a separate assembly bundled inside `Lumeo.DataGrid`. On Blazor WebAssembly you can opt-in to lazy-load it — see the [setup guide](/docs/services/datagrid-export#lazy-loading). No extra package, same install command.

.csproj

<ItemGroup\>
  <PackageReference Include\="Lumeo"            Version\="3.12.1" />
  <!-- add only the satellites you need: -->
  <PackageReference Include\="Lumeo.Charts"    Version\="3.12.1" />
  <PackageReference Include\="Lumeo.DataGrid"  Version\="3.12.1" />
  <PackageReference Include\="Lumeo.Editor"    Version\="3.12.1" />
  <PackageReference Include\="Lumeo.Scheduler" Version\="3.12.1" />
  <PackageReference Include\="Lumeo.Gantt"     Version\="3.12.1" />
  <PackageReference Include\="Lumeo.Motion"    Version\="3.12.1" />
  <PackageReference Include\="Lumeo.PdfViewer" Version\="3.12.1" />
  <PackageReference Include\="Lumeo.Maps"      Version\="3.12.1" />
  <PackageReference Include\="Lumeo.CodeEditor" Version\="3.12.1" />
</ItemGroup\>

No extra namespace imports needed

`@using Lumeo` already covers satellite components — no extra `@using` directives are required. The `lumeo add <component>` CLI also detects which satellite a component belongs to and prompts to install it if it isn't referenced yet.

2

### Register services

In your `Program.cs`, register the Lumeo services. This registers `ToastService`, `OverlayService`, `ThemeService`, `KeyboardShortcutService`, and `ComponentInteropService`:

Program.cs

builder.Services.AddLumeo();

3

### Add global using

Add the namespace to your `_Imports.razor` so components are available everywhere:

\_Imports.razor

@using Lumeo
@using Lumeo.Services

4

### Add providers to your layout

Add `<ToastProvider />` and `<OverlayProvider />` to your `MainLayout.razor` so toast notifications and programmatic overlays work:

MainLayout.razor

<div class\="min-h-screen"\>
    @Body
    <ToastProvider />
    <OverlayProvider />
</div\>

5

### Include styles and scripts

Add the following to your `index.html` (WebAssembly) or `App.razor`/`_Host.cshtml` (Server). Since [v1.3.0](https://www.nuget.org/packages/Lumeo/1.3.0) the package ships a pre-compiled Tailwind utility stylesheet, so no local Tailwind build is required:

index.html / App.razor

<!-- Design tokens: CSS variables + keyframes -->
<link rel\="stylesheet" href\="\_content/Lumeo/css/lumeo.css" />

<!-- Pre-compiled Tailwind utilities used by Lumeo components -->
<link rel\="stylesheet" href\="\_content/Lumeo/css/lumeo-utilities.css" />

<!-- Theme bootstrap (prevents flash of unstyled content) -->
<script src\="\_content/Lumeo/js/theme.js"\></script\>

<!-- Component interop (loaded on demand) -->
<script src\="\_content/Lumeo/js/components.js" type\="module"\></script\>

Using Tailwind in your own markup?

If you want to write utility classes yourself, keep your Tailwind v4 build and drop `lumeo-utilities.css` — your own build will emit every utility Lumeo needs plus anything you use on top. See the [README](https://github.com/Brain2k-0005/Lumeo/blob/master/README.md) for the `@theme` / `@source` snippet.

6

### (Optional) Configure localization

Built-in English and German translations ship in v1.2.0+. Select a culture via the standard ASP.NET request-localization middleware, or override specific strings during `AddLumeo`:

Program.cs

builder.Services.AddLumeo(opts =>
{
    opts.Add("de", "DataGrid.NoData", "Keine Datensätze");
    opts.AddMany("fr", new Dictionary<string, string\>
    {
        \["DataGrid.NoData"\]     = "Aucune donnée",
        \["Pagination.Previous"\] = "Précédent",
    });
});

## Usage

Once installed, you can start using components directly in your `.razor` files. Here is a simple example using the `Button` component:

Page.razor

<!-- Default button -->
<Button\>Click me</Button\>

<!-- Variant and size -->
<Button Variant\="Button.ButtonVariant.Outline" Size\="Button.ButtonSize.Sm"\>
    Save changes
</Button\>

<!-- With click handler -->
<Button OnClick\="HandleClick"\>Submit</Button\>

Every component accepts Class and AdditionalAttributes

Pass extra Tailwind classes with `Class` and any remaining HTML attributes are forwarded to the root element via `AdditionalAttributes`.

## Theming

Lumeo uses CSS custom properties (variables) for all colors and design tokens. There are no hardcoded hex values or raw HSL colors anywhere in the component library. This means:

-   Dark mode works automatically via variable swaps — no `dark:` Tailwind prefixes needed.
-   You can swap the entire palette by overriding a handful of CSS variables in your own stylesheet.
-   Multiple built-in themes are available out of the box.

Open the **customizer panel** in the top-right of any docs page (the icon, or press Ctrl + B) to preview every built-in theme against the live page and copy the matching `lumeo apply --preset` command.

## Services

Lumeo ships with 5 scoped services that handle common app concerns. All are registered by `builder.Services.AddLumeo()` and can be injected anywhere with `@inject`.

### ToastService

Show, dismiss, and update toast notifications from C# code. Supports variants (success, error, warning, info), action buttons, persistent toasts, and async promise toasts.

[View docs →](docs/services/toast)

### OverlayService

Open dialogs, sheets, drawers, and alert dialogs programmatically from code. Await results with `ShowDialogAsync<T>()`.

[View docs →](docs/services/overlay)

### ThemeService

Switch between light/dark/system mode, change color schemes at runtime, and listen for theme changes with events.

[View docs →](docs/services/theme)

### KeyboardShortcutService

Register global keyboard shortcuts like `ctrl+k` or `ctrl+shift+p` from C# code. Auto-cleanup with IDisposable handles.

[View docs →](docs/services/keyboard-shortcuts)

### ComponentInteropService

Low-level JS interop helpers used by components: scroll locking, focus traps, click-outside detection, clipboard, element positioning, and more. Useful for building custom components.

[View docs →](docs/services/component-interop)

## Components

Lumeo ships with 75+ components organized into nine categories:

### Form

Button, Cascader, Checkbox, Color Picker, Combobox, Date Picker, Date Time Picker, File Upload, Filter, Form, Input, Label, Mention, Number Input, OTP Input, Radio Group, Segmented, Select, Slider, Switch, Tag Input, Textarea, Time Picker, Toggle, Toggle Group.

[Browse Form components →](components/button)

### Layout

Accordion, Aspect Ratio, Calendar, Card, Carousel, Collapsible, Resizable, Scroll Area, Separator, Tabs.

[Browse Layout components →](components/card)

### Feedback

Alert, Badge, Empty State, Progress, Result, Skeleton, Spinner, Toast.

[Browse Feedback components →](components/alert)

### Overlay

Alert Dialog, Command, Context Menu, Dialog, Drawer, Dropdown Menu, Hover Card, Popover, Sheet, Tooltip, Tour.

[Browse Overlay components →](components/dialog)

### Navigation

Breadcrumb, Menubar, Navigation Menu, Pagination, Sidebar, Steps.

[Browse Navigation components →](components/breadcrumb)

### Data Display

Avatar, Chart, Data Grid, Data Table, Descriptions, Image, Rating, Statistic, Table, Timeline.

[Browse Data Display components →](components/table)

### Utility

Affix, Back To Top, Kbd, Scrollspy, Transfer, Tree View, Watermark.

[Browse Utility components →](components/kbd)

### Theme

Theme Switcher, Theme Toggle.

[Browse Theme components →](components/theme-switcher)

## You're ready to build.

Services registered, stylesheets linked, providers mounted. Time to start composing.

[Browse components](components/button) [See blocks](blocks)