@bug-on/m3-expressive

v1.3.3

Published

10 days ago

Material Design 3 Expressive React components

0High
0Medium
0Low

nguyentruongton

react tailwind material-design-3 md3 ui-library components bug-on

@bug-on/m3-expressive

A high-performance, accessible React component library built strictly following the Material Design 3 Expressive 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
👉 GitHub Repository

📦 Installation

pnpm add @bug-on/m3-expressive motion
# or
npm install @bug-on/m3-expressive motion

Peer Dependencies

🛠️ 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):

/* 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 <Icon /> component renders Material Symbols Outlined variable font glyphs:

Option A: Google Fonts CDN (Recommended for Web)

// 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 (
    <html lang="en">
      <head>
        <MaterialSymbolsPreconnect />
      </head>
      <body>{children}</body>
    </html>
  );
}

Option B: Offline / Self-Hosted Assets

For air-gapped networks, enterprise privacy, or offline PWAs, install @bug-on/m3-fonts:

pnpm add @bug-on/m3-fonts

@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

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 (
    <MD3ThemeProvider sourceColor="#00639b" defaultMode="system">
      <div className="p-6 bg-m3-surface text-m3-on-surface rounded-m3-extra-large shadow-m3-elevation-2 max-w-sm space-y-4">
        <h2 className="text-m3-title-large font-bold">Welcome Back</h2>
        
        <TextField
          label="Email Address"
          variant="outlined"
          leadingIcon={<Icon name="mail" />}
        />
        
        <div className="flex gap-2">
          <Chip variant="filter" selected label="Remember me" />
        </div>
        
        <Button
          colorStyle="filled"
          size="md"
          icon={<Icon name="arrow_forward" />}
        >
          Sign In
        </Button>
      </div>
    </MD3ThemeProvider>
  );
}

🎨 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 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:

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@bug-on/m3-expressive

📖 Documentation & Interactive Demos

📦 Installation

Peer Dependencies

🛠️ Configuration & Setup (Tailwind CSS v4)

Icon Font Setup (Material Symbols Outlined)

Option A: Google Fonts CDN (Recommended for Web)

Option B: Offline / Self-Hosted Assets

🧩 Subpath Exports Guide

🚀 Quick Code Example

🎨 Component Inventory

🔘 Buttons & Actions

🏷️ Chips

📝 Forms & Inputs

📅 Date & Time Pickers

🧭 Navigation & Toolbars

📜 Menus

🖼️ Overlays & Sheets

⚡ Feedback & Status

📐 Layout, Surfaces & Carousel

🔮 Shapes & Motion Engine

🤖 AI Agent Integration

📚 Locating LLM Documentation

💡 Suggested Prompt for your AI Assistant

⚖️ License