English | 简体中文
Material 3 Expressive React component library built on @base-ui/react, with HCT color generation, spring motion tokens, m3e.json CLI, and built-in i18n/RTL support.
pnpm add m3eui
# or
npm install m3euiPeer dependencies: react >= 18.0.0, react-dom >= 18.0.0.
Initialize m3e.json and generate static theme CSS:
npx m3eui init --seed "#6750A4" --variant expressive --locale en-USMount M3EProvider:
import "./styles/m3e-theme.css";
import "m3eui/styles.css";
import { M3EProvider, Button, Switch, TimePickerField } from "m3eui";
import m3eConfig from "../m3e.json";
export function App() {
return (
<M3EProvider config={m3eConfig}>
<Button variant="filled">Save</Button>
<Switch label="Notifications" defaultChecked />
<TimePickerField label="Release time" defaultValue="09:30" />
</M3EProvider>
);
}import "./styles/m3e-theme.css";
import "m3eui/styles.css";
import { M3EProvider, getM3EInitScript } from "m3eui";
import m3eConfig from "../m3e.json";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<head>
<meta name="color-scheme" content="light dark" />
<script dangerouslySetInnerHTML={{ __html: getM3EInitScript() }} />
</head>
<body>
<M3EProvider config={m3eConfig}>{children}</M3EProvider>
</body>
</html>
);
}By default, colors come from the static m3e-theme.css generated by m3eui init / sync. To recompute HCT palettes dynamically in the browser (e.g. live theme switcher), pass themeEngine={generateM3EThemeTokens}:
import { M3EProvider } from "m3eui";
import { generateM3EThemeTokens } from "m3eui/tokens";
import m3eConfig from "../m3e.json";
export function DynamicApp({ children }: { children: React.ReactNode }) {
return (
<M3EProvider config={m3eConfig} themeEngine={generateM3EThemeTokens}>
{children}
</M3EProvider>
);
}| Path | Description |
|---|---|
m3eui |
RSC-safe barrel for components, hooks, M3EProvider, M3EPortal, config, i18n, and tokens |
m3eui/styles.css |
Component stylesheet (--m3e-* custom properties + light-dark()) |
m3eui/tokens |
Pure RSC-safe 61-role HCT color synthesis (primary/secondary/tertiary/error/success/warning), spring solver, corner topology, parseShortcutKeys, and 35 MaterialShapes (getMaterialShape) |
m3eui/tokens.json |
Precomputed token and polygon JSON |
m3eui/i18n |
RSC-safe en-US, zh-CN, ja-JP, ar-SA dictionaries and M3EMessageKey types |
m3eui/config |
RSC-safe defineM3EConfig, resolveM3EConfig (colorMode: "system" default), serializeM3EConfig, generateM3EStaticThemeCss |
m3eui/primitives |
Re-exported @base-ui/react primitives |
m3eui/cli |
Programmatic CLI API |
m3eui/m3e.schema.json |
JSON Schema for m3e.json |
m3eui/components/* |
Individual component modules |
npx m3eui init --seed "#0B6B58" --variant vibrant --locale zh-CN
npx m3eui sync
npx m3eui locale --list
npx m3eui locale fr-FR --out src/i18n/fr-FR.ts --force
npx m3eui doctor| Scope | Exports |
|---|---|
| Core & Config | M3EProvider, M3EPortal, CSPProvider, useM3E, useM3EI18n, useM3EPortalContainer, getM3EInitScript, defineM3EConfig, resolveM3EConfig, serializeM3EConfig, generateM3EStaticThemeCss, useM3EScalarSpring, useM3ECornerSpring, useM3ECornerSpringRef, usePressHoldState |
| Components | Accordion (variant), Alert (controlled/uncontrolled open), AlertDialog, AlertDialogClose, AppBarRow, Avatar, AvatarGroup, Badge, Breadcrumb, Button (pressed → toggle), ButtonGroup, Card, Carousel, Checkbox, CheckboxGroup, Chip (onClick → assist, selected → filter, onRemove → input), CircularProgressIndicator (wavy), ColorPicker, ColorPickerField, ColorSwatch, Combobox (multiple), CommandPalette, ContextMenu, CopyButton, DataTable, DatePicker, DatePickerField (mode: "single" | "range", modal), Dialog, DialogClose, Divider, DragHandle, DropdownMenu, Empty, FAB (xs/sm/md/lg, default sm; children → extended), FABMenu, Fieldset, FileUpload, FileUploadDropzone, FloatingToolbar, Form, IconButton (pressed → toggle), Kbd, LinearProgressIndicator, List (variant="segmented"), ListItem, LoadingIndicator (contained), MaterialShapeView, Meter, NavigationBar, NavigationRail (expanded / collapsible / modal incl. "auto" / density="compact"), NumberField, OTPField, Pagination, Popover (openOnHover), PopoverClose, Radio, RadioGroup, ScrollArea, SearchBar, SearchView, Select (multiple), Sheet (side), SheetClose, Skeleton, Slider, Snippet, SplitButton, Switch, Tab, Tabs, TabsList, TabsPanel, TextField (multiline), TimePicker, TimePickerField (modal), Tooltip (subhead / action → rich, keyboard-gated action focus), TopAppBar, useM3EToast |
| Directory | Description |
|---|---|
packages/m3eui |
m3eui npm package |
apps/playground |
Interactive component showcase |
pnpm install
pnpm dev
pnpm build
pnpm typecheck
pnpm test
pnpm m3e:doctor