Skip to content
boltguoPublic

About

Material 3 Expressive React component library built on Base UI | 基于 Base UI 的 M3E 组件库,HCT 动态色彩、物理弹簧与多语言/RTL

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

m3eui

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.

Install

pnpm add m3eui
# or
npm install m3eui

Peer dependencies: react >= 18.0.0, react-dom >= 18.0.0.

Quick Start

Initialize m3e.json and generate static theme CSS:

npx m3eui init --seed "#6750A4" --variant expressive --locale en-US

Mount 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>
  );
}

Next.js App Router

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>
  );
}

Runtime theming

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>
  );
}

Subpath Exports

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

CLI

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

Components

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

Development

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

License

Apache-2.0

About

Material 3 Expressive React component library built on Base UI | 基于 Base UI 的 M3E 组件库,HCT 动态色彩、物理弹簧与多语言/RTL

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Contributors

Languages