Box

The Box component is a generic, theme-aware container with access to CSS utilities from MUI System.

Introduction

The Box component is a generic container for grouping other components. It's a fundamental building block when working with Joy UI—you can think of it as a <div> with extra built-in features, like access to your app's theme and the sx prop.

Usage

The Box component differs from other containers available in Joy UI in that its usage is intended to be multipurpose and open-ended, just like a <div>. Components like Stack and Sheet, by contrast, feature usage-specific props that make them ideal for certain use cases: Stack for one-dimensional layouts, and Sheet for surfaces that need access to Joy UI's global variants.

Basics

import Box from '@mui/joy/Box';

The Box component renders as a <div> by default, but you can swap in any other valid HTML tag or React component using the component prop. The demo below replaces the <div> with a <section> element:

This Box renders as an HTML section element.

import * as React from 'react';
import Box from '@mui/joy/Box';

export default function BoxBasic() {
  return (
    <Box component="section" sx={{ p: 2, border: '1px dashed grey' }}>
      This Box renders as an HTML section element.
    </Box>
  );
}

import * as React from 'react';
import Box from '@mui/joy/Box';

export default function BoxBasic() {
  return (
    <Box component="section" sx={{ p: 2, border: '1px dashed grey' }}>
      This Box renders as an HTML section element.
    </Box>
  );
}

Press Enter to start editing

Customization

With MUI System props

As a CSS utility component, the Box supports all MUI System properties. You can use them as props directly on the component.

This Box uses MUI System props for quick customization.

import * as React from 'react';
import Box from '@mui/joy/Box';

export default function BoxSystemProps() {
  return (
    <Box
      height={200}
      width={200}
      my={4}
      display="flex"
      alignItems="center"
      gap={4}
      p={2}
      sx={{ border: '2px solid grey' }}
    >
      This Box uses MUI System props for quick customization.
    </Box>
  );
}

import * as React from 'react';
import Box from '@mui/joy/Box';

export default function BoxSystemProps() {
  return (
    <Box
      height={200}
      width={200}
      my={4}
      display="flex"
      alignItems="center"
      gap={4}
      p={2}
      sx={{ border: '2px solid grey' }}
    >
      This Box uses MUI System props for quick customization.
    </Box>
  );
}

Press Enter to start editing

With the sx prop

Use the sx prop to quickly customize any Box instance using a superset of CSS that has access to all the style functions and theme-aware properties exposed in the MUI System package. The demo below shows how to apply colors from the theme using this prop:

import * as React from 'react';
import { Box, ThemeProvider } from '@mui/joy';

export default function BoxSx() {
  return (
    <ThemeProvider
      theme={{
        colorSchemes: {
          light: {
            palette: {
              primary: {
                400: '#38bdf8',
                700: '#0369a1',
              },
            },
          },
        },
      }}
    >
      <Box
        sx={{
          width: 100,
          height: 100,
          borderRadius: 1,
          bgcolor: 'primary.700',
          '&:hover': {
            bgcolor: 'primary.400',
          },
        }}
      />
    </ThemeProvider>
  );
}

import * as React from 'react';
import { Box, ThemeProvider } from '@mui/joy';

export default function BoxSx() {
  return (
    <ThemeProvider
      theme={{
        colorSchemes: {
          light: {
            palette: {
              primary: {
                400: '#38bdf8',
                700: '#0369a1',
              },
            },
          },
        },
      }}
    >
      <Box
        sx={{
          width: 100,
          height: 100,
          borderRadius: 1,
          bgcolor: 'primary.700',
          '&:hover': {
            bgcolor: 'primary.400',
          },
        }}
      />
    </ThemeProvider>
  );
}

Press Enter to start editing

Anatomy

The Box component is composed of a single root <div> element:

<div className="MuiBox-root">
  <!-- contents of the Box -->
</div>

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

<Box />