Skip to main content

​
Getting Started

Learn how to install and use MUI System in your project.

​
Installation

Install MUI System from npm: 
npm install @mui/system @emotion/react @emotion/styled
or with yarn: 
yarn add @mui/system @emotion/react @emotion/styled

​
Peer Dependencies

MUI System requires the following peer dependencies:
  • react >= 17.0.0
  • @emotion/react >= 11.0.0
  • @emotion/styled >= 11.0.0

​
Basic Usage

​
Using the Box Component

The simplest way to get started is with the Box component: 
import { Box } from '@mui/system';

function App() {
  return (
    <Box
      sx={{
        width: 300,
        height: 300,
        backgroundColor: 'primary.main',
        '&:hover': {
          backgroundColor: 'primary.dark',
        },
      }}
    />
  );
}

​
Using Style Props

You can also use system props directly: 
import { Box } from '@mui/system';

function App() {
  return (
    <Box
      width={300}
      height={300}
      bgcolor="primary.main"
      p={2}
      m={1}
    >
      Content
    </Box>
  );
}

​
Setting Up a Theme

Create a custom theme to define your design tokens: 
import { createTheme, ThemeProvider } from '@mui/system';

const theme = createTheme({
  palette: {
    primary: {
      main: '#1976d2',
      dark: '#115293',
    },
    background: {
      default: '#fff',
      paper: '#f5f5f5',
    },
  },
  spacing: 8,
  breakpoints: {
    values: {
      xs: 0,
      sm: 600,
      md: 900,
      lg: 1200,
      xl: 1536,
    },
  },
});

function App() {
  return (
    <ThemeProvider theme={theme}>
      <Box bgcolor="primary.main" p={2}>
        Themed content
      </Box>
    </ThemeProvider>
  );
}

​
Using styled()

Create custom styled components with the styled() API: 
import { styled } from '@mui/system';

const StyledDiv = styled('div')(({ theme }) => ({
  backgroundColor: theme.palette.primary.main,
  padding: theme.spacing(2),
  borderRadius: theme.shape.borderRadius,
}));

function App() {
  return <StyledDiv>Styled content</StyledDiv>;
}

​
Responsive Design

Use arrays or objects for responsive values: 
import { Box } from '@mui/system';

// Array syntax (mobile-first)
<Box width={[1, 1/2, 1/3]} p={[1, 2, 3]} />

// Object syntax (named breakpoints)
<Box
  width={{ xs: '100%', sm: '50%', md: '33.33%' }}
  p={{ xs: 1, sm: 2, md: 3 }}
/>

​
TypeScript

MUI System is written in TypeScript and provides full type safety: 
import { Box, SxProps, Theme } from '@mui/system';

const sx: SxProps<Theme> = {
  width: 300,
  height: 300,
  backgroundColor: 'primary.main',
};

function App() {
  return <Box sx={sx}>Content</Box>;
}

​
Extending the Theme Type

To add custom properties to the theme: 
import '@mui/system';

declare module '@mui/system' {
  interface Theme {
    customProperty: string;
  }
  interface ThemeOptions {
    customProperty?: string;
  }
}

const theme = createTheme({
  customProperty: 'value',
});

​
Importing Style Functions

You can import individual style functions for use in custom components: 
import { spacing, palette, compose } from '@mui/system';
import { styled } from '@mui/system';

const MyComponent = styled('div')(compose(spacing, palette));

<MyComponent p={2} color="primary.main">
  Composed style functions
</MyComponent>

​
Available Style Functions

MUI System provides the following style function groups:
  • borders - Border utilities (border, borderRadius, etc.)
  • display - Display utilities (display, overflow, etc.)
  • flexbox - Flexbox utilities (flexDirection, justifyContent, etc.)
  • grid - CSS Grid utilities (gap, gridColumn, etc.)
  • palette - Color utilities (color, bgcolor)
  • positions - Position utilities (position, top, left, etc.)
  • shadows - Shadow utilities (boxShadow)
  • sizing - Sizing utilities (width, height, etc.)
  • spacing - Spacing utilities (margin, padding)
  • typography - Typography utilities (fontSize, fontWeight, etc.)

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us