``` The IIFE bundle exposes the global `Expressive` object. The compiled stylesheet ships `@font-face` rules for variable Material Symbols (outlined, rounded, and sharp, with the opsz / wght / FILL / GRAD axes), Roboto and the Noto Sans fallback at 400 / 500 / 700 in Latin, Cyrillic, Greek, Vietnamese and (Noto Sans) Devanagari subsets. Keep `dist/fonts/` next to `dist/css/` so the relative font URLs resolve. Override the brand/plain tokens when the page uses different typefaces. Do not load the older Material Icons stylesheet; use `.material-symbols`. ## ES module setup ```js import '@expressivecss/expressive/css'; import { AutoInit, Tooltip } from '@expressivecss/expressive'; AutoInit(); const element = document.querySelector('.custom-tooltip'); if (element) Tooltip.init(element, { position: 'top' }); ``` ## Sass setup For smaller consumer bundles, import selected components from `@expressivecss/expressive/modular` and call their `.init()` methods after markup exists. Call the required document behaviors explicitly, such as `Forms.Init()` for input enhancements and `Dialogs.Init()` for light dismissal. Do not repeat these calls alongside the root entry. `AutoInit` still includes the full registry. Both ESM entries share constructors; hosting them directly requires their chunks. Use `@use "pkg:@expressivecss/expressive/scss/custom" with ($components: ("icons-material-design", "tabs"), $utilities: ());` with Sass's Node package importer. Tokens and base remain included. Lists preserve the given order; `null` includes a whole group and `()` omits it. For FormSelect and Datepicker use `("icons-material-design", "buttons", "menu", "forms", "datepicker")`. Add `"docked-display"` before `"forms"` for the optional docked picker, or `"dialog"` and `"modal-display"` for the modal one. `$expressive-include-fonts: false` lets consumers supply subset font faces, but also removes the text font declarations. Restore Roboto and Noto Sans 400/500/700 or explicitly choose alternative typefaces. Retain icon ligatures and variable axes, and include dynamic icons: Chips and dismissible Snackbar use `close`, and expandable navigation rail summaries use `expand_more`. The README includes font declarations and the full initialization table. Full fonts remain available. Frosted glass is off by default. `--expressive-glass: true` on `:root` or an ancestor frosts menus, tooltips, popovers, dialogs, the command palette, sheets, the snackbar, navigation bar and rail, toolbars, and the search view; it has no effect on the surface itself. `--expressive-glass-blur` (16px) and `--expressive-glass-opacity` (72%) tune it, and `false` turns it off in a region. Sass `$expressive-glass`, `-blur`, and `-opacity` set the defaults. Reduced-transparency and more-contrast preferences restore solid surfaces. ```scss @use "@expressivecss/expressive/src/sass/expressive"; ``` The Sass entry point emits four cascade layers in this order: `tokens`, `base`, `components`, and `utilities`. Utilities therefore override component-layer declarations without selector-specificity escalation. Unlayered application CSS overrides normal declarations in all framework layers. ## Themes and color roles Set `theme="light"` or `theme="dark"` on the root element: ```html ``` Switch at runtime by changing the attribute: ```js document.documentElement.setAttribute('theme', 'dark'); ``` Add the `vibrant` attribute to an element to resolve the surface roles in its subtree to the tertiary container instead of a neutral surface. It repaints nothing itself — it redeclares tokens, and the components under it that already read those roles follow. The live Material tokens use the `--md-sys-color-` naming scheme. Override `--md-source` to generate the primary, secondary, tertiary, neutral, and neutral-variant ramps at runtime. Use the live role token in component CSS rather than a `-light` or `-dark` source token. ```css :root { --md-source: #6750a4; } .custom-panel { color: var(--md-sys-color-on-surface); background: var(--md-sys-color-surface); } ``` ## Responsive model ExpressiveCSS uses the exact M3 window size classes: Compact `< 600px`, Medium `600–839px`, Expanded `840–1199px`, Large `1200–1599px`, and Extra-large `>= 1600px`. The 12-column grid maps those classes to `.s`, `.m`, `.l`, `.xl`, and `.xxl` prefixes respectively. ## JavaScript initialization Initialize all registered components in a context: ```js Expressive.AutoInit(); Expressive.AutoInit(document.querySelector('#app'), { Tooltip: { position: 'top' } }); ``` Opt an element out when it needs manual options: ```html Hover ``` Or give the element its options in markup. `AutoInit()` reads a `data--options` attribute holding a JSON object, where `` is the component name in kebab case (`Menu` reads `data-menu-options`, `FormSelect` reads `data-form-select-options`, and `.date-picker` reads `data-datepicker-options` because the name comes from the component, not the class) and the keys are the option names used in script: ```html ``` - Options passed to `AutoInit(context, options)` win for the keys they set; a nested object such as `i18n` counts as one key. Tooltip reads its own `data-tooltip`, `data-tooltip-id` and `data-position` again each time it opens, so those win over both. Set those, and Menu's `contextMenu` (`data-context-menu`), in one place. - Markup can set only options whose default is a string, number, boolean, array or plain object, with a value of the same kind. Nested keys are checked against the default object, and one rejected nested key leaves the whole object at its default. An object whose default is empty, such as FormSelect's `menuOptions`, accepts no keys from markup. Items of a non-empty default array need the kind of its first item. Callbacks, elements, options with a `null` default, Autocomplete's `allowUnsafeHTML` and the `data` lists of Chips and Autocomplete stay script-only. - Invalid JSON, unknown keys and wrong kinds are skipped with a console warning, and those options keep their defaults. A value that passes the checks but still makes a component throw stops `AutoInit()`, as it would from script. - Direct `init()` calls do not read the attribute. Menus inside a `.menubar` take Menubar's `menuOptions` instead. `AutoInit()` scans once. Pass `{ watch: true }` as a third argument to keep watching the context: components start in markup added later and are destroyed when their markup is removed. The call returns a function that stops watching; without `watch` it does nothing. ```js const stop = Expressive.AutoInit(document.body, {}, { watch: true }); document.querySelector('main').insertAdjacentHTML('beforeend', html); // started in a later microtask function unmount() { stop(); // stops watching; started components keep running } ``` - Added markup starts like the first scan, with the same options, `data--options` attributes and `no-autoinit` opt-out. The added element itself is checked as well as its descendants. - An element that already has an instance keeps it, so starting a component yourself before adding its element works, and components that build their own markup (the Datepicker's month and year selects) keep their instances. - Removal destroys only instances `AutoInit()` would have started; `no-autoinit` elements are left to your code. An element moved elsewhere in the page keeps its instance. Class and attribute changes on elements already in the page are ignored. - `stop()` first handles changes not yet reported, so markup added just before the call still starts. - Markup inserted at runtime becomes live components. Sanitize user content first, and drop component classes and `data--options` attributes you don't want started. - Shadow roots are not entered. Pass a `ShadowRoot` as the context to watch inside one. Call it once per root. A component that throws while starting stops the rest of that batch; later changes are still handled. `AutoInit()` recognizes these public components and selectors: | Component | Selector | | --- | --- | | `AppBar` | `header.medium, header.large, header:has(> :is(nav:not(.tabs, .navigation-bar, .navigation-rail), .bar) > .search-bar)` | | `Autocomplete` | `.autocomplete` | | `ButtonGroup` | `.button-group` | | `Cards` | `article:has(> aside[id]:not([id=""])):not(:has(> aside ~ aside)):has(> button.card-reveal-trigger[type="button"], > :not(aside) button.card-reveal-trigger[type="button"])` | | `ExpandingCard` | `article.expanding-card:has(> dialog.expanding-card-dialog)` | | `Carousel` | `.carousel` | | `Chips` | `.chips` | | `Confetti` | `.confetti` | | `Particles` | `canvas.particles` | | `Keypad` | `.keypad, .keyboard` | | `ColorPicker` | `.color-picker` | | `BarChart` | `.bar-chart` | | `PieChart` | `.pie-chart` | | `HeatmapChart` | `.heatmap-chart` | | `RadarChart` | `.radar-chart` | | `RadialChart` | `.radial-chart` | | `MixedChart` | `.mixed-chart` | | `ScatterChart` | `.scatter-chart` | | `SankeyChart` | `.sankey-chart` | | `FunnelChart` | `.funnel-chart` | | `TreemapChart` | `.treemap-chart` | | `ColumnChart` | `.column-chart` | | `CommandPalette` | `dialog.command-palette` | | `Questionnaire` | `form.questionnaire` | | `Datepicker` | `.date-picker` | | `LineChart` | `.line-chart` | | `Menu` | `.menu-trigger` | | `MessageScroller` | `.message-scroller` | | `PullToRefresh` | `.pull-to-refresh` | | `LoadingOverlay` | `.loading-overlay` | | `SwipeActions` | `.list.swipeable` | | `InputMask` | `input[data-mask]` of type text, tel, search, url or password | | `ShowMore` | `.show-more` | | `CurrencyInput` | `input[data-currency]` of type text | | `Lightbox` | `.lightboxed` | | `NavigationRail` | `.navigation-rail` | | `ScrollSpy` | `.scrollspy` | | `BackToTop` | `.back-to-top` | | `FormSelect` | `select` without `data-tree` | | `TreeSelect` | `select[data-tree]` | | `Cascader` | `.cascader` | | `Tabs` | `.tabs` | | `Timepicker` | `.time-picker` | | `Tooltip` | `.tooltipped` | | `HoverCard` | `.hover-card-trigger` | | `FloatingActionButton` | `.fab-menu` | | `Menubar` | `.menubar` | `Snackbar`, `CharacterCounter`, and `Slider` are intentionally not in the registry. Construct or initialize them through their documented APIs. Importing the bundle also installs document-level keyboard/focus handlers and initializes the shared Forms, Chips, Slider, Cards, ExpandingCard, Dialogs, BottomSheets, SideSheets, Copy, Theme, PaneResize, ImageCompare, Tour, Sortable, and TransferList behaviors. ## Component lifecycle Most per-element JavaScript components share this pattern: ```js const element = document.querySelector('.component'); const instance = Expressive.ComponentName.init(element, options); const current = Expressive.ComponentName.getInstance(element); current?.destroy(); ``` `init()` also accepts a NodeList or HTMLCollection and returns an array of component instances. Empty collections return an empty array. Re-initializing an element destroys its previous instance first. Component-specific sections below define additional methods, properties, callbacks, and option defaults. Menu, Lightbox, NavigationRail, Cards and ExpandingCard fire DOM events from the element they were initialized on: `expressive:open` and `expressive:close` when the state changes, then `expressive:opened` and `expressive:closed` when the motion ends. Cards and ExpandingCard fire only `expressive:open` and `expressive:close`. Each event follows the matching `on…` callback, which still works. The events bubble and are composed, so a document listener sees components inside open shadow roots; check `event.target` because nested components bubble too. Closing a Menu or Lightbox from its `expressive:open` listener stops it opening. ```js document.addEventListener('expressive:open', (event) => { if (event.target.matches('.menu-trigger')) analytics.track('menu-open'); }); ``` Choices and changes carry what was chosen in `event.detail`: | Event | Fired by | `detail` | | --- | --- | --- | | `expressive:change` | Tabs, Carousel | `{ panel }`, `{ item, dragged }` | | `expressive:select` | Menu, Datepicker, Timepicker | `{ item }`, `{ date }`, `{ hours, minutes }` | | `expressive:confirm`, `expressive:cancel` | Datepicker, Timepicker | none | | `expressive:autocomplete` | Autocomplete | `{ values }` | | `expressive:create` | Autocomplete, from its `Add` row | `{ text }` | | `expressive:chip-add`, `chip-select`, `chip-delete` | Chips | `{ chip }` | | `expressive:change` | ButtonGroup, Menu checkbox and radio items, ScrollSpy (from the section), Tour | `{ button, pressed }`, `{ item, checked }`, `{ link }`, `{ step, index }` | | `expressive:open`, `expressive:close` | Tooltip, HoverCard, Snackbar, Tour, ShowMore | Tour's close: `{ completed }` | | `expressive:action`, `expressive:closed` | Snackbar | none | | `expressive:copy` | Copy buttons | `{ text, copied }` | | `expressive:refresh` | Pull-to-refresh | `{ waitUntil }` | | `expressive:swipetoggle` | Swipe actions | `{ row, open }` | | `expressive:transfer` | Transfer list, from the container | `{ rows, from, to }` | | `expressive:reject` | Opted-in drop zones, from the wrapper | `{ input, files, rejected, reason }`; reason is `type`, `size` or `count`; noncancelable | | `expressive:change`, `expressive:sort`, `expressive:resize`, `expressive:filter`, `expressive:page` | Data tables, from the wrapper | `{ selected }`, `{ header, column, direction }`, `{ header, column, width }`, `{ query }`, `{ page, pageSize }`; `sort`, `filter` and `page` are cancelable | An Autocomplete or Select input hosts a Menu, so it also fires that Menu's `expressive:open`, `expressive:close` and `expressive:select`. A callback that changes the choice again, such as an `onShow` that selects another tab, leaves only the event for the final choice. Tooltip fires `expressive:open` and `expressive:close` when it actually shows and hides, after its delays. A snackbar fires its events from the snackbar itself; `expressive:closed` comes just before it leaves the page. Tour's `expressive:close` says whether the Done button finished it. ## Public JavaScript surface The main bundle exports: - `AutoInit`, `Forms`, and `version` - `Copy` and `Theme`, the copy button and theme switch behaviors - `PaneResize`, `ImageCompare`, `Tour`, `Sortable` and `TransferList` behaviors, and the `Menubar` component - `Dialogs`, `BottomSheets`, and `SideSheets` - `Autocomplete`, `FloatingActionButton`, `Cards`, `Carousel`, and `CharacterCounter` - `Chips`, `Datepicker`, `Menu`, and `Lightbox` - `Slider` and `ScrollSpy` - `FormSelect`, `NavigationRail`, and `Tabs` - `Timepicker`, `Snackbar`, and `Tooltip` --- # Getting started ## Getting started Build Material Design 3 interfaces from semantic HTML, with light and dark themes and accessible components. ### Installation Expressive comes in two different forms. You can select which version you want depending on your preference and expertise. The project is at version `0.16.0` and is still growing, so the usual path is to build from the repository. #### Expressive This is the standard version that comes with both the minified and unminified CSS and JavaScript files. After you build the project, copy the files from `dist/`. This option requires little to no setup. Use this if you are unfamiliar with Sass. #### Sass This version is the source SCSS in `src/sass`. By choosing this version you have more control over which layers to include. You will need a Sass compiler if you choose this option. #### From source Clone the repository and build the compiled CSS and JavaScript: ```sh npm install npm run build ``` The compiled assets are written to `dist/`: ```text dist/ ├── css/ │ ├── expressive.css │ └── expressive.min.css ├── fonts/ ├── js/ │ ├── expressive.cjs │ ├── expressive.js │ ├── expressive.min.js │ ├── expressive.mjs │ └── modular.mjs └── types/ ``` #### NPM The package name is `@expressivecss/expressive`. This release contains source files as well as the compiled CSS and JavaScript files. ```sh npm install @expressivecss/expressive ``` #### Yarn Or you can add the package with yarn. ```sh yarn add @expressivecss/expressive ``` ### Setup #### Project structure After building, copy the compiled files into the directory where your website is located. Your directory will look something like this. You'll notice that there are two sets of the files. The `min` means that the file is compressed to reduce load times. These minified files are usually used in production while it is better to use the unminified files during development. ```text MyWebsite/ |--css/ | |--expressive.css | |--expressive.min.css | |--fonts/ | |--material-symbols-outlined.woff2 | |--js/ | |--expressive.js | |--expressive.min.js | |--index.html ``` #### HTML setup Next you just have to make sure you link the files properly in your webpage. Generally it is wise to import JavaScript files at the end of the body to reduce page load time. Follow the example below on how to import Expressive into your webpage. ```html ``` #### Initialize JavaScript The browser bundle exposes the framework as the global `Expressive` object. Importing the JavaScript installs shared document behaviors (forms, chips, cards, and a few others), but it does not call `AutoInit()` automatically. Call it after the page has loaded so components such as navigation rails, tooltips, and tabs start themselves. `AutoInit()` scans `document.body` by default. Pass a container to limit the scan, or add the `no-autoinit` class to an element that should be initialized manually. ```js Expressive.AutoInit(); Expressive.AutoInit(document.querySelector('#app'), { Tooltip: { position: 'top' } }); ``` #### ES modules Import the framework or individual components from the module build: ```js import { AutoInit, Tooltip } from './js/expressive.mjs'; AutoInit(); const element = document.querySelector('.custom-tooltip'); Tooltip.init(element, { position: 'top' }); ``` #### Themes Expressive uses the `theme` attribute on the root element. The default is light. Switch themes at runtime by updating the attribute. ```html ``` ```js document.documentElement.setAttribute('theme', 'dark'); ``` ### Templates Start from a documented layout instead of an empty page. These two pages show how Expressive structures content, and you can copy the markup they use. #### Grid #### Helpers ### Sass setup This section is only relevant if you chose to use the Sass sources. #### Compiling Sass Instead of only a CSS folder, the repository contains many `.scss` files which contain the styles of individual layers and components. The browser cannot interpret Sass, so you must compile `src/sass/expressive.scss` into a regular CSS file. At this point you can link this newly outputted file in your HTML page. From the repository, the npm script does that for you: ```sh npm run build:css ``` In another Sass project, use the framework's Sass entry point: ```scss @use "@expressivecss/expressive/src/sass/expressive"; ``` When working directly in this repository, the entry point is `src/sass/expressive.scss`. ```text MyWebsite/ |--css/ | |--expressive.css <-- compiled from scss/expressive.scss | |--js/ | |--expressive.js | |--scss/ | |--expressive.scss | |--abstracts/ | |--tokens/ | |--utilities/ | |--base/ | |--components/ | |--index.html ``` --- # CSS foundations ## Themes Light and dark schemes, the theme attribute, and custom tokens. Expressive maps Material Design 3 color tokens onto live `--md-sys-color-*` custom properties. Components, buttons, and the color utilities all read those live names, so flipping the scheme recolors the page without extra classes. Three rules decide which pair is live, in this order: 1. Default: `:root` and `:host` set `color-scheme: light dark`, so `light-dark()` follows the OS. 2. `:root[theme='auto']` is the same follow-OS value, written explicitly. 3. `:root[theme='light']` and `:root[theme='dark']` lock the scheme and override the OS. Each live token is `light-dark(var(--md-sys-color--light), var(--md-sys-color--dark))`, written once and resolved against the element's used `color-scheme` — there is no `prefers-color-scheme` media query behind the colors. Because it resolves at the point of use, setting `color-scheme` on any element re-themes that subtree, and native controls follow the same scheme. Each of the three rules above is paired with a `:host([theme='…'])` twin, so a shadow host can be pinned to a theme the same way `` can. Every token-declaring rule in the sheet carries that pairing: the sheet is supported as a shadow root's *only* stylesheet, and `:root` matches the document element and nothing else. This site starts as ``. The theme control in the app bar is a menu: Light, Dark, and Auto. The choice is written to `localStorage` and restored before first paint so a reload does not flash the wrong scheme. ### Reading the theme Put a short inline script in ``, before the stylesheet paints, if you want to restore a saved choice and avoid a flash of the wrong scheme. The framework does not run this: the `Theme` behavior saves a choice when a control is clicked, but restoring it before first paint is the page's job. Without a `theme` attribute the CSS already follows the OS through `color-scheme: light dark`. Setting the attribute to `light` or `dark` locks the scheme; `auto` goes back to following the OS. The snippet below reads a stored value first, then falls back to the OS preference, then writes the attribute so the override is explicit. ```html ``` Keep this inline rather than in an external file so it runs before the first paint. Setting `theme="light"` in the HTML and never changing it locks the page to light until JavaScript flips the attribute. ### Changing the theme Switch schemes by writing the attribute: ```js document.documentElement.setAttribute('theme', 'dark'); ``` Or let the `Theme` behavior do it. A click on any element with `data-theme-set="light"`, `"dark"` or `"auto"` writes the attribute and saves the choice to `localStorage` under `theme`, the key the snippet above reads. The root bundle starts it on load, and the modular entry with `Theme.Init()`. It marks every theme control as current or not: `aria-checked` on `menuitemradio` and `radio` roles, `aria-pressed` on anything else. Other values are ignored. ```html