toc

Migration

Version 3.0 renames most elements from md- to md-gb- and moves them to Material 3 Expressive.

Version 3.0 renames most elements from md-* to md-gb-* and moves them to Material 3 Expressive. Many names stay the same, but some attributes and slots change, and a few components are no longer recommended. This page lists the changes. The 2.5.0 docs stay on the root of this site.

Start with the styles

Link to “Start with the styles”

Load the 3.0 design tokens once per document:

HTML

<md-gb-button color="filled">Save</md-gb-button>

import '@material/web/labs/gb/components/button/md-gb-button.js';
import {adoptStyles} from '@material/web/labs/gb/styles/adopt-styles.js';
import {styles as m3Styles} from '@material/web/labs/gb/styles/m3.cssresult.js';

adoptStyles(document, [m3Styles]);

Then import each md-gb-* element you use from @material/web/labs/gb/components/.

Element and attribute map

Link to “Element and attribute map”

Element names change as listed below. Where the table says "dropped", the 2.5.0 attribute has no 3.0 counterpart and you can remove it.

2.5.0	3.0	Changes
`md-filled-button`	`md-gb-button`	`color="filled"`
`md-elevated-button`	`md-gb-button`	`color="elevated"`
`md-filled-tonal-button`	`md-gb-button`	`color="tonal"`
`md-outlined-button`	`md-gb-button`	`color="outlined"`
`md-text-button`	`md-gb-button`	`color="text"`
`md-icon-button`	`md-gb-icon-button`	`color="standard"`; `toggle` and `flip-icon-in-rtl` dropped
`md-filled-icon-button`	`md-gb-icon-button`	`color="filled"`
`md-filled-tonal-icon-button`	`md-gb-icon-button`	`color="tonal"`
`md-outlined-icon-button`	`md-gb-icon-button`	`color="outlined"`
`md-fab`, `md-branded-fab`	`md-gb-fab`	`variant` becomes `color` (`primary-container`, `secondary-container`, `tertiary-container`); `size="large"` becomes `size="lg"`; `label` becomes text content; `size`, `lowered` and `variant` dropped
`md-checkbox`	`md-gb-checkbox`	`touch-target` dropped
`md-radio`	`md-gb-radio`	`touch-target` dropped
`md-switch`	`md-gb-switch`	none
`md-slider`	`md-gb-slider`	`aria-*` label and value text attributes renamed (see below)
`md-divider`	`md-gb-divider`	`inset`, `inset-start` and `inset-end` dropped
`md-list`, `md-list-item`	`md-gb-list`, `md-gb-list-item`	`start` slot becomes `leading`, `end` becomes `trailing`, `trailing-supporting-text` becomes `trailing-text`; `headline` slot is unwrapped
`md-menu`, `md-menu-item`	`md-gb-menu`, `md-gb-menu-item`	`positioning`, `menu-corner` and `anchor-corner` dropped on `md-gb-menu`; the same slot changes as lists
`md-linear-progress`	`md-gb-progress`	`indeterminate`, `buffer` and `four-color` dropped
`md-circular-progress`	`md-gb-progress circular`	`indeterminate` and `four-color` dropped
`md-filled-text-field`	`md-gb-text-field`	none (filled is the default)
`md-outlined-text-field`	`md-gb-text-field`	`variant="outlined"`
`md-filled-select`	`md-gb-select`	`menu-positioning`, `clamp-menu-width`, `menu-align` and `quick` dropped
`md-outlined-select`	`md-gb-select`	`variant="outlined"`, same drops as above
`md-select-option`	`md-gb-select-option`	`headline` slot is unwrapped; `start` becomes `leading`, `end` becomes `trailing`
`md-dialog`	`md-gb-dialog`	the `content` slot is removed, so the content goes in the default slot
`md-tabs`	`md-gb-tabs`	`variant="secondary"` when it holds secondary tabs; `auto-activate` and `active-tab-index` dropped
`md-primary-tab`, `md-secondary-tab`	`md-gb-tab`	the label goes in `slot="label"`; `inline-icon`, `has-icon`, `active` and `icon-only` dropped
`md-chip-set`	`md-gb-chip-set`	none
`md-assist-chip`	`md-gb-chip`	`color="elevated"` if it was `elevated`; `label` becomes text content
`md-filter-chip`	`md-gb-chip`	`type="filter"`; same color rule
`md-input-chip`	`md-gb-chip`	`type="input"` with `removable`
`md-suggestion-chip`	`md-gb-chip`	`type="suggestion"`; same color rule
`md-icon`	`md-gb-icon`	inside a button, icon button, FAB or tab, the `slot="icon"` is removed and the icon goes in DOM order

If the icon is not an md-icon (for example an inline SVG), wrap it in md-gb-icon.

Attributes to rename by hand

Link to “Attributes to rename by hand”

Converting the elements does not rename every attribute. Update these by hand:

md-gb-slider: aria-label-start becomes label-start, aria-label-end becomes label-end, aria-valuetext-start becomes valuetext-start, and aria-valuetext-end becomes valuetext-end. The aria- prefix is reserved for ARIA attributes, so the 3.0 names do not use it. value-label-start and value-label-end keep their names.
md-gb-dialog: full-screen applies only on compact windows. Above that, the dialog is a basic dialog with the same slots. Add always-full-screen to keep the full-screen layout at every window size. The 2.5.0 md-dialog has no full-screen attribute, so this is new in 3.0.

Recommendations that changed

Link to “Recommendations that changed”

The Expressive spec no longer recommends some 2.5.0 patterns. The components remain available, but for new work use the replacement below.

Segmented buttons are replaced by a connected button group: md-gb-button-group variant="connected".
Navigation drawer is replaced by an expanded navigation rail: md-gb-nav-rail with expanded. Use modal when it overlays content.
Bottom app bar is replaced by a docked toolbar: md-gb-toolbar docked.
Medium and large app bars are replaced by medium and large flexible app bars: md-gb-app-bar size="md" and size="lg".
Small FABs and surface-colored FABs are replaced by the default FAB size and the container colors (primary-container, secondary-container, tertiary-container).

Watch out for

Link to “Watch out for”

Chips and FABs no longer take their text from a label attribute. Put the text in the element instead, as the table shows.
An md-gb-* element that is not imported is not upgraded, so it renders as an unknown element.
Selectors, queries and tests that use the old md-* tag names need the new names too.

Migration

Start with the styles

Element and attribute map

Attributes to rename by hand

Recommendations that changed

Watch out for

Download & copy

Download

Copy

Customize theme