Migrating from legacy StrataKit

This guide provides the necessary steps for migrating from legacy StrataKit components (e.g. @stratakit/bricks) to MUI-based StrataKit implementation.

Note

Migration to StrataKit MUI can be done gradually, since both libraries can coexist in the same project.

Migration steps

1. Set up StrataKit MUI

   Follow the set up StrataKit MUI guide to install the necessary dependencies and set up your project.

2. Replace @stratakit/foundations with @stratakit/mui

   Replace the Root component from @stratakit/foundations with the Root component from @stratakit/mui. This unlocks the ability to use MUI components within the Root. Legacy StrataKit components nested within the Root will continue to work, enabling gradual migration.

   import { Root } from "@stratakit/foundations";
   import { Root } from "@stratakit/mui";

   Replace usage of Icon component from @stratakit/foundations with the Icon component from @stratakit/mui. Continue using icons from the @stratakit/icons package.

   import { Icon } from "@stratakit/foundations";
   import { Icon } from "@stratakit/mui";

   Once all direct usage of @stratakit/foundations has been replaced, it is safe to remove the dependency.

   npm uninstall @stratakit/foundations

3. Replace @stratakit/bricks with @mui/material

   Replace the usage of components from @stratakit/bricks with their MUI counterparts. Refer to the use MUI components section below for the component mapping and additional guidance.

   import { Button } from "@stratakit/bricks";
   import Button from "@mui/material/Button";

   Once all usage of @stratakit/bricks has been replaced, it is safe to remove the dependency.

   npm uninstall @stratakit/bricks

4. Continue using @stratakit/structures

   Replace the usage of AccordionItem, Banner and Chip components from @stratakit/structures package with their MUI counterparts.

   import { Chip } from "@stratakit/structures";
   import Chip from "@mui/material/Chip";

   Continue using other components from @stratakit/structures package, as they are not affected by the migration to StrataKit MUI.

Use MUI components

Replace legacy StrataKit component usage with their MUI counterparts.

StrataKit component	MUI component
AccordionItem	Accordion
Anchor	Link
Avatar	Avatar
Badge	Badge
Banner	Alert
Button	Button
Checkbox	Checkbox
Chip	Chip
Description	FormHelperText
Divider	Divider
Field	FormControl
IconButton	IconButton
Kbd	-
Label	FormLabel
ProgressBar	LinearProgress
Radio	Radio
Select	Select
Skeleton	Skeleton
Spinner	CircularProgress
Switch	Switch
Text	Typography
TextBox	TextField
Tooltip	Tooltip
VisuallyHidden	-

Tip

Read additional StrataKit MUI component documentation for more details on usage and customization.

AccordionItem

• Replace the AccordionItem component from @stratakit/structures with the Accordion component from @mui/material. See Accordion examples for reference.
• Change AccordionItem.Root component to Accordion component.
• Change AccordionItem.Header component to AccordionSummary component.
• Change AccordionItem.Content component to AccordionDetails component.
• Change AccordionItem.Label component to Typography component.
• Remove usage of AccordionItem.Button component. Button is configured via AccordionSummary component instead.
• Remove usage of AccordionItem.Decoration component. Provide custom content to AccordionSummary component instead.
• Use expandIconWrapper slot to replace usage of AccordionItem.Marker component.
• Use heading slot to replace usage of AccordionItem.Heading component.

Anchor

• Replace the Anchor component from @stratakit/bricks with the Link component from @mui/material. See Link examples for reference.

• Change tone prop to color prop.

  tone value	color value
  "neutral"	"secondary"
  "accent"	"primary"

• Usage of compositional API is not available. External marker is not supported.

Avatar

• Replace the Avatar component from @stratakit/bricks with the Avatar component from @mui/material. See Avatar examples for reference.
• Change image prop to:
  • children prop for icon avatars.
  • src prop for image avatars.
• Change initials prop to children prop.
• Change size prop to explicit height and width CSS properties.

Badge

• Replace the Badge component from @stratakit/bricks with the Badge component from @mui/material. See Badge examples for reference.

• Use inline prop to display the badge in normal document flow.

• Change tone prop to color prop.

  tone value	color value
  "neutral"	"secondary"
  "accent"	"primary"
  "info"	"info"
  "positive"	"success"
  "attention"	"warning"
  "critical"	"error"

• Remove variant prop. Only "standard" variant is supported by MUI component.

Banner

• Replace the Banner component from @stratakit/structures with the Alert component from @mui/material. See Alert examples for reference.

• Change Banner, Banner.Root components to Alert component.

• Change usage of label prop and Banner.Label component to AlertTitle component.

• Change usage of message prop and Banner.Message component to children prop.

• Change usage of actions prop and Banner.Actions component to action prop. Customize action container via action slot.

• Change usage of icon prop and Banner.Icon component to icon prop. Customize icon container via icon slot.

• Change onDismiss prop to onClose prop.

• Change usage of Banner.DismissButton component to onClose, closeText props and closeButton, closeIcon slots.

• Change tone prop to severity prop.

  tone value	severity value
  "neutral"	"success"
  "info"	"info"
  "positive"	"success"
  "attention"	"warning"
  "critical"	"error"

• Update value of variant prop.

  Before	After
  "outline"	"outlined"

Button

• Replace the Button component from @stratakit/bricks with the Button component from @mui/material. See Button examples for reference.

• Change tone prop to color prop.

  tone value	color value
  "neutral"	"secondary"
  "accent"	"primary"

• Update value of variant prop.

  Before	After
  "solid"	"contained"
  "outline"	"outlined"
  "ghost"	"text"

• Use startIcon and endIcon props to display icons.

Checkbox

• Replace the Checkbox component from @stratakit/bricks with the Checkbox component from @mui/material. See Checkbox examples for reference.
• Use FormControlLabel component to label the checkbox.

Chip

• Replace the Chip component from @stratakit/structures with the Chip component from @mui/material. See Chip examples for reference.

• Change Chip, Chip.Root components to Chip component.

• Change usage of label prop and Chip.Label component to label prop. Customize label container via label slot.

• Change onDismiss prop to onDelete prop.

• Change usage of Chip.DismissButton component to onDelete, deleteIcon props.

• Update value of variant prop.

  Before	After
  "outline"	"outlined"
  "solid"	"filled"

Description

• Replace the Description component from @stratakit/bricks with the FormHelperText component from @mui/material.
• Remove tone prop. Instead use error prop to display the message in an error state.

Divider

• Replace the Divider component from @stratakit/bricks with the Divider component from @mui/material. See Divider examples for reference.
• Remove unsupported bleed prop.
• Replace unsupported presentational prop with a render prop that overrides the element type and role: render={<div role={undefined} />}.

Field

• Replace the Field component from @stratakit/bricks with the FormControl component from @mui/material.
• Change Field.Root, Field.Label and Field.Control components with FormControlLabel.
• Use FormControl, FormLabel and FormGroup components to group multiple fields.
• Change Field.Description component with FormHelperText component to display a description.
• Change Field.ErrorMessage component with FormHelperText component to display an error message.

Kbd

• Change Kbd component to a <kbd> element.

IconButton

• Replace the IconButton component from @stratakit/bricks with the IconButton component from @mui/material. See IconButton examples for reference.
• Change icon prop to children prop.
• Remove active prop. Use ToggleButton component to display a toggle button.
• Remove dot prop. Wrap the icon in a Badge component to display a badge.
• Remove labelVariant prop. Use a visually hidden label, without a wrapper Tooltip.
• Remove variant prop. Only "ghost" variant is supported by MUI component.

ProgressBar

• Replace the ProgressBar component from @stratakit/bricks with the LinearProgress component from @mui/material. See Progress examples for reference.

• Remove unsupported size prop.

• Change tone prop to color prop.

  tone value	color value
  "neutral"	"secondary"
  "accent"	"primary"

Radio

• Replace the Radio component from @stratakit/bricks with the Radio component from @mui/material. See Radio examples for reference.
• Use FormControlLabel component to label the radio control.
• Use RadioGroup component to group multiple radio buttons.

Select

• Replace the Select component from @stratakit/bricks with the Select component from @mui/material. See Select examples for reference.
• Change Select.HtmlSelect component to NativeSelect or Select component.
• Remove variant prop. Only "outlined" variant is supported by MUI component.

Skeleton

• Replace the Skeleton component from @stratakit/bricks with the Skeleton component from @mui/material. See Skeleton examples for reference.

• Remove size prop. Use font-size CSS property or width and height properties based on the skeleton variant.

• Update value of variant prop.

  Before	After
  "text"	"text"
  "object"	"rounded"

Spinner

• Replace the Spinner component from @stratakit/bricks with the CircularProgress component from @mui/material. See Progress examples for reference.

• Change the value of size prop. MUI size prop uses pixel values or custom units when a string is provided.

• Change tone prop to color prop.

  tone value	color value
  "neutral"	"secondary"
  "accent"	"primary"

Switch

• Replace the Switch component from @stratakit/bricks with the Switch component from @mui/material. See Switch examples for reference.
• Use FormControlLabel component to label the switch control.

Text

• Replace the Text component from @stratakit/bricks with the Typography component from @mui/material. See Typography examples for reference.

• Update value of variant prop.

  Before	After
  "display-lg"	"h1"
  "display-md"	"h2"
  "display-sm"	"h3"
  "headline-lg"	"h4"
  "headline-md"	"h5"
  "headline-sm"	"h6"
  "body-lg"	"body1"
  "body-md"	"body2"
  "body-sm"	"body2"
  "caption-lg"	"caption"
  "caption-md"	"caption"
  "caption-sm"	"caption"
  "mono-sm"	"body2" (with font-family: var(--stratakit-font-family-mono) CSS property)

TextBox

• Replace the TextBox component from @stratakit/bricks with the TextField component from @mui/material. See TextField examples for reference.
• Set label prop instead of the Field.Label component to display a label.
• Set startAdornment or endAdornment properties of slotProps.input instead of the TextBox.Icon component to display an icon.
• Set multiline prop to display a multi-line text area, instead of using the TextBox.Textarea component.
• Use helperText prop to display a description, instead of using the Field.Description component. Additionally, set error prop to display an error, instead of using the Field.ErrorMessage component.

Tooltip

• Replace the Tooltip component from @stratakit/bricks with the Tooltip component from @mui/material. See Tooltip examples for reference.
• Change content prop to title prop.
• Change type prop with a "label" value to describeChild prop with a false value: type="label" → describeChild={false}.
• "none" value of type is not supported. Manually override aria- attributes instead.

VisuallyHidden

• Use visuallyHidden CSS utility instead.

Common props

accessibleWhenDisabled prop

• accessibleWhenDisabled prop is not supported.

render prop

• Continue using render prop to customize the rendering of the components. render prop is preferred over the component prop where available.