Migrate from @material/web

What stays and what changes

• The same tokens. Components read the --md-sys-* custom properties (colour roles, typescale, shape, elevation, state), the names a Material Theme Builder export sets. Keep your theme and link @lit-material/tokens/css/index.css once for the baseline. The .md-typescale-* classes are in @lit-material/tokens/css/typography.css under the same names.
• One package per component. import "@material/web/button/filled-button.js" becomes import "@lit-material/button", which registers every button variant.
• Variants are attributes. One element per component: <md-outlined-text-field> is <lit-material-text-field variant="outlined">, <md-filled-tonal-button> is <lit-material-button variant="tonal">. Labels that were attributes (label on chips and FABs) are text content.
• Component tokens differ. Per-component tokens such as --md-filled-button-container-color have no counterparts. Each lit-material element lists its own --lit-material-* properties and CSS parts on its page; colours and shapes come from the system tokens.
• Forms. Text fields, selects, checkboxes, radios, switches, sliders and buttons are form-associated through ElementInternals: FormData, constraint validation and reset work as with native controls.
• Server rendering. Every component is tested against @lit-labs/ssr, and @lit-material/vite renders whole apps on the server. See Server rendering.
• More components. Data table, date and time pickers, navigation drawer, rail and bar, snackbar, tooltip, stepper and the rest of the catalogue, which @material/web doesn't have.

Run the codemod

Commit first: the codemod rewrites files in place. A dry run prints every change and warning and writes nothing:

npx @lit-material/codemod md-web src --dry-run
npx @lit-material/codemod md-web src

It reads HTML (with parse5, a spec-compliant parser), Lit templates in .ts/.js, JSX and TSX, and CSS, and edits the text in place, so formatting, comments and expressions stay as they were. Binding syntax is kept: .prefixText=${p} becomes .prefix=${p}, Angular's [selected] becomes [checked]. It ends with the packages to install:

  changed  src/app.ts:12: <md-outlined-text-field> → <lit-material-text-field variant="outlined">
  changed  src/app.ts:12: <md-outlined-text-field> prefix-text → prefix
  warning  src/app.ts:31: <md-slider> range: lit-material-slider is single-value; a two-thumb range is not supported

Install what the rewritten files use:  npm install @lit-material/tokens @lit-material/button @lit-material/text-field …

Anything without a confident mapping is a warning with its file and line, never a silent change: unknown md-* elements, attributes with no counterpart, bound values that would need mapping, class imports (import { MdDialog }), md-* names in selectors and strings, and component tokens. Running it twice changes nothing the second time. The same rewrite is a function, for your own tooling: import { transform } from "@lit-material/codemod".

Element by element

This table is the codemod's own mapping, so it is what the codemod does. Attributes not listed carry over unchanged.

Imports follow the elements: @material/web/<folder>/<file>.js becomes the element's package, once per file. @material/web/all.js is reported with the imports to use instead, and left for you to replace.

What needs a person

• Icons. <md-icon>settings</md-icon> draws a Material Symbols ligature from an icon font. lit-material-icon loads no font, so the word shows as text: register the SVGs with registerIcons() and use name, or slot an <svg>. The codemod reports each ligature.
• Script code. The codemod changes markup and imports. Code that reads switch.selected (now checked), tabs.activeTabIndex (now selected), queries md-* selectors, or imports md-web classes is reported, not rewritten.
• Labels. A <label for> pointing at lit-material-checkbox, -radio or -switch doesn't toggle it (checked in Chromium); wrapping the control in the <label> does. Prefer the element's label attribute, which also names it for assistive technology.
• Component tokens. Each --md-<component>-* token is reported with the lit-material element's own properties and parts to use instead.
• Missing pieces. No chip set, submenus, two-thumb slider, linear progress buffer, secondary tab style, or standalone ripple, focus ring and elevation elements (components draw their own). The table lists every attribute and event left in place.