# @bug-on/m3-expressive
[](https://www.npmjs.com/package/@bug-on/m3-expressive)
[](https://opensource.org/licenses/MIT)
[](https://tailwindcss.com/)
A high-performance, accessible React component library built strictly following the [Material Design 3 Expressive](https://m3.material.io/) design system specifications. Features fluid spring physics, flexible shape morphing, dynamic Material You color generation (2025 spec), SSR support, and native compatibility with Next.js 16 (App Router / Turbopack), React 19, and Tailwind CSS v4.
---
## 📖 Documentation & Interactive Demos
For live interactive component playgrounds, code examples, and API references, visit:
👉 **[Official Documentation & Live Demos](https://bug-on-md3.vercel.app)**
👉 **[GitHub Repository](https://github.com/nguyentruongton/bug-on-md3-expressive)**
---
## 📦 Installation
```bash
pnpm add @bug-on/m3-expressive motion
# or
npm install @bug-on/m3-expressive motion
```
### Peer Dependencies
| Package | Version Requirement | Description |
| :--- | :--- | :--- |
| `react` | `^19.0.0` | React core framework |
| `react-dom` | `^19.0.0` | React DOM renderer |
| `motion` | `>=12.0.0` *(optional)* | Spring physics animation engine (FABs, Carousels, Tabs, Sheets) |
| `tailwindcss` | `>=4.0.0` | Tailwind CSS v4 CSS-first framework |
---
## 🛠️ Configuration & Setup (Tailwind CSS v4)
> [!WARNING]
> This library requires **Tailwind CSS v4** (CSS-first architecture via `@import "tailwindcss"`). Tailwind CSS v3 is not supported.
Import the required stylesheets into your application's root CSS entry point (e.g., `app/globals.css` or `src/index.css`):
```css
/* 1. Core Tailwind CSS v4 */
@import "tailwindcss";
/* 2. MD3 Expressive Tokens & Theme Resets (Required) */
@import "@bug-on/m3-expressive/index.css";
/* 3. (Optional) Extended MD3 Tailwind Utilities (Elevations, Transitions, Shiki) */
@import "@bug-on/m3-tailwind";
/* 4. (Optional) Typography Preset Classes */
@import "@bug-on/m3-expressive/typography.css";
```
### Icon Font Setup (Material Symbols Outlined)
The `` component renders **Material Symbols Outlined** variable font glyphs:
#### Option A: Google Fonts CDN (Recommended for Web)
```tsx
// app/layout.tsx
import "@bug-on/m3-expressive/material-symbols-cdn.css";
import { MaterialSymbolsPreconnect } from "@bug-on/m3-expressive";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
#### Option B: Offline / Self-Hosted Assets
For air-gapped networks, enterprise privacy, or offline PWAs, install `@bug-on/m3-fonts`:
```bash
pnpm add @bug-on/m3-fonts
```
```css
@import "@bug-on/m3-fonts/material-symbols.css";
@import "@bug-on/m3-fonts/typography.css";
```
---
## 🧩 Subpath Exports Guide
Optimize your bundle size and tree-shaking by importing directly from modular subpaths:
| Subpath Import | Module Contents |
| :--- | :--- |
| `@bug-on/m3-expressive/core` | `MD3ThemeProvider`, `createMd3ExpressiveTheme`, `generateM3Theme`, `applyTheme`, `useTheme`, `useThemeMode`, `Icon`, `Ripple`, `MaterialSymbolsPreconnect`, `cn` |
| `@bug-on/m3-expressive/buttons` | `Button`, `IconButton`, `FAB`, `ExtendedFAB`, `FABMenu`, `SplitButton`, `ButtonGroup`, `ButtonDistribute` |
| `@bug-on/m3-expressive/forms` | `TextField`, `Checkbox`, `TriStateCheckbox`, `RadioButton`, `RadioGroup`, `Switch`, `Slider`, `RangeSlider`, `Select`, `Chip`, `Search` |
| `@bug-on/m3-expressive/navigation` | `NavigationBar`, `NavigationRail`, `NavigationDrawer`, `Tabs`, `Tab`, `TabsList`, `TabsContent`, `SmallAppBar`, `MediumFlexibleAppBar`, `LargeFlexibleAppBar`, `BottomAppBar`, `DockedToolbar`, `HorizontalFloatingToolbar`, `VerticalFloatingToolbar`, `Menu`, `ContextMenu`, `VerticalMenu`, `Search` |
| `@bug-on/m3-expressive/overlays` | `Dialog`, `DialogFullScreenContent`, `Drawer`, `BottomSheet`, `BottomSheetModal`, `SideSheet`, `SideSheetModal` |
| `@bug-on/m3-expressive/feedback` | `Snackbar`, `SnackbarProvider`, `useSnackbar`, `ProgressIndicator` (linear, circular, wavy), `LoadingIndicator`, `Badge`, `BadgedBox`, `PlainTooltip`, `RichTooltip` |
| `@bug-on/m3-expressive/layout` | `Card`, `Carousel` (Morphing layout, Multi-browse, Uncontained), `Divider`, `List`, `ListItem`, `ListDivider`, `ScrollArea`, `CodeBlock`, `TableOfContents`, `Text`, `Typography` |
| `@bug-on/m3-expressive/pickers` | `DatePicker`, `DatePickerDialog`, `DatePickerInput`, `DateRangePicker`, `TimePicker`, `TimePickerDialog`, `TimeInput`, `useDatePickerState`, `useDateRangePickerState`, `useTimePickerState` |
| `@bug-on/m3-expressive/shapes` | `ShapeMedia`, `ShapeSvg`, `ShapeIcon`, `useShapeMorph`, MD3 shape morphing engine |
---
## 🚀 Quick Code Example
```tsx
import { MD3ThemeProvider } from "@bug-on/m3-expressive/core";
import { Button } from "@bug-on/m3-expressive/buttons";
import { TextField, Chip } from "@bug-on/m3-expressive/forms";
import { Icon } from "@bug-on/m3-expressive";
export default function App() {
return (
Welcome Back
}
/>
}
>
Sign In
);
}
```
---
## 🎨 Component Inventory
### 🔘 Buttons & Actions
- **`Button`**: Filled, Elevated, Tonal, Outlined, Text, Tertiary, Primary-Fixed, and Tertiary-Fixed color styles.
- **`IconButton`**: Standard, Filled, Tonal, Outlined, with toggle state support.
- **`FAB` / `ExtendedFAB`**: Small, Medium, Large, Extended with icon motion and responsive collapsing.
- **`FABMenu`**: Speed-dial expandable Floating Action Button menu with spring transition physics.
- **`SplitButton`**: Combined primary button action with trailing menu dropdown.
- **`ButtonGroup` / `ButtonDistribute`**: Segmented button groups with shared morphing shapes and dynamic width distribution.
### 🏷️ Chips
- **`Chip`**: Assist, Filter, Input, and Suggestion chip variants.
- **`ChipGroup`**: Horizontally scrollable and wrapping chip containers.
- **Features**: Leading avatars/icons, animated selection checkmarks, and trailing remove/action icons.
### 📝 Forms & Inputs
- **`TextField`**: Outlined and Filled text inputs with floating labels, character count, error helper text, and icon slots.
- **`Checkbox` / `TriStateCheckbox`**: Standard and indeterminate checkboxes with animated checkmarks.
- **`RadioButton` / `RadioGroup`**: Single-selection groups with smooth scale transitions.
- **`Switch`**: Expressive toggle switch with optional custom inline icons.
- **`Slider` / `RangeSlider`**: Continuous and discrete sliders with value tooltips and step indicators.
- **`Select`**: Exposed dropdown menu and autocomplete search select (`searchable`, `matchTriggerWidth`).
- **`Search` / `SearchBar` / `SearchView`**: Search input bars and full-screen docked/expanded search surfaces.
### 📅 Date & Time Pickers
- **`DatePicker` / `DatePickerDialog` / `DatePickerInput`**: Modal and inline calendar date pickers with hoisted `useDatePickerState()`.
- **`DateRangePicker`**: Range selection date picker with `useDateRangePickerState()`.
- **`TimePicker` / `TimePickerDialog` / `TimeInput`**: Dial clock face and numeric time inputs with `useTimePickerState()`.
### 🧭 Navigation & Toolbars
- **`NavigationBar`**: Bottom navigation bar with animated pill active indicator and label visibility controls.
- **`NavigationRail`**: Vertical navigation bar for tablets and desktop viewports.
- **`NavigationDrawer` / `Drawer`**: Standard docked and modal side navigation drawers.
- **`Tabs` / `Tab` / `TabsList` / `TabsContent`**: Primary and Secondary tabs with sliding underline indicator.
- **`SmallAppBar` / `MediumFlexibleAppBar` / `LargeFlexibleAppBar` / `BottomAppBar`**: Collapsible header app bars with scroll behavior binding (`useAppBarScroll`).
- **`DockedToolbar` / `HorizontalFloatingToolbar` / `VerticalFloatingToolbar`**: Floating and docked adaptive toolbars with optional embedded FAB.
### 📜 Menus
- **`Menu`**: Popup menus with cascading submenu support and trigger width matching.
- **`ContextMenu`**: Right-click contextual popover menu.
- **`VerticalMenu`**: Always-visible static vertical navigation menu with container shape morphing.
### 🖼️ Overlays & Sheets
- **`Dialog` / `DialogFullScreenContent`**: Expressive modal dialogs, alert confirmations, and full-screen dialogs.
- **`BottomSheet` / `BottomSheetModal`**: Draggable bottom sheets with snap points and drag gestures (`useBottomSheet`).
- **`SideSheet` / `SideSheetModal`**: Contextual docked and modal side panels.
### ⚡ Feedback & Status
- **`Snackbar` / `SnackbarProvider` / `useSnackbar`**: Imperative queue toast notification system with action triggers.
- **`ProgressIndicator`**: Linear and circular progress indicators (determinate, indeterminate, wavy shape `shape="wavy"`, and track stop dots).
- **`LoadingIndicator`**: Expressive indeterminate loading animations.
- **`Badge` / `BadgedBox`**: Small status dots and numerical count notification badges.
- **`PlainTooltip` / `RichTooltip`**: Informative plain tooltips and rich interactive popover tooltips with carets and actions.
### 📐 Layout, Surfaces & Carousel
- **`Carousel`**: MD3 Expressive morphing carousel supporting Multi-browse, Uncontained, and Hero layouts (`useCarouselKeylines`, `useCarouselA11y`).
- **`Card`**: Elevated, Filled, and Outlined surface cards with header, media, content, and footer slots.
- **`Divider`**: Full-bleed, inset, and decorative wavy dividers (`buildWavePath`).
- **`List` / `ListItem` / `ListDivider`**: Single and multi-line list rows with avatar, checkbox, and action controls.
- **`ScrollArea`**: Lightweight customized scrollable container.
- **`CodeBlock`**: Syntax-highlighted code container with copy button.
- **`TableOfContents`**: Interactive documentation navigation anchor list.
- **`Text` / `Typography`**: Expressive typography renderers with standard MD3 type scales.
### 🔮 Shapes & Motion Engine
- **`ShapeMedia` / `ShapeSvg` / `ShapeIcon`**: Morphing media frames supporting MD3 expressive geometry (Full, Extra Large, Large, Medium, Small, Star, Clover, Arch, etc.).
- **`useShapeMorph`**: Dynamic spring-based corner shape interpolation hook.
---
## 🤖 AI Agent Integration
This package ships with machine-readable LLM documentation (`llms.txt` and `llms-full.txt`) adhering to the [llmstxt.org](https://llmstxt.org/) standard. When installed in your project, AI coding assistants (Cursor, GitHub Copilot, Claude Code, ChatGPT Codex) can read the bundled specification directly to understand APIs and avoid hallucinating props.
### 📚 Locating LLM Documentation
- **Local (in your project after install)**:
- `node_modules/@bug-on/m3-expressive/llms-full.txt` *(Full API & Gotchas reference - Recommended)*
- `node_modules/@bug-on/m3-expressive/llms.txt` *(Quick overview)*
- **Remote CDN**:
- `https://unpkg.com/@bug-on/m3-expressive/llms-full.txt`
- `https://cdn.jsdelivr.net/npm/@bug-on/m3-expressive/llms-full.txt`
- `https://raw.githubusercontent.com/nguyentruongton/bug-on-md3-expressive/main/llms-full.txt`
### 💡 Suggested Prompt for your AI Assistant
Add this instruction to your project's `CLAUDE.md`, `.cursorrules`, or system prompt:
```markdown
Before generating or modifying UI components using @bug-on/m3-expressive, read:
- Local: node_modules/@bug-on/m3-expressive/llms-full.txt
- CDN: https://unpkg.com/@bug-on/m3-expressive/llms-full.txt
```
---
## ⚖️ License
[MIT](./LICENSE)