Responsive Styles

Chakra UI supports responsive styles out of the box. Instead of manually adding @media queries and adding nested styles throughout your code, Chakra UI allows you to provide object and array values to add mobile-first responsive styles.

We use the @media(min-width) media query to ensure your interfaces are mobile-first.

Responsive syntax relies on the breakpoints defined in the theme object. Chakra UI provides default breakpoints.

Default breakpoints are defined using em unit:

const breakpoints = {
  base: "0em", // 0px
  sm: "30em", // ~480px. em is a relative unit and is dependant on the font size.
  md: "48em", // ~768px
  lg: "62em", // ~992px
  xl: "80em", // ~1280px
  "2xl": "96em", // ~1536px
};

To make styles responsive, you can use either the array or object syntax.

The Array syntax#

All style props accept arrays as values for mobile-first responsive styles. This is the recommended method.

Let's say you have a Box with the following properties:

<Box bg="red.200" w="400px">
  This is a box
</Box>

To make the width or w responsive using the array syntax, here's what you need to do:

<Box bg="red.200" w={[300, 400, 500]}>
  This is a box
</Box>

To interpret array responsive values, Chakra UI converts the values defined in theme.breakpoints and sorts them in ascending order. Afterward, we map the values defined in the array to the breakpoints.

// These are the default breakpoints
const breakpoints = {
  base: "0em", // 0px
  sm: "30em", // ~480px. em is a relative unit and is dependant on the font-size.
  md: "48em", // ~768px
  lg: "62em", // ~992px
  xl: "80em", // ~1280px
  "2xl": "96em", // ~1536px
};

// Internally, we transform to this
const breakpoints = ["0em", "30em", "48em", "62em", "80em", "96em"];

Here's how to interpret this syntax w={[300, 400, 500]}:

• 300px: From 0em upwards
• 400px: From 30em upwards
• 500px: From 48em upwards

To skip certain breakpoints, you can pass null to any position in the array to avoid generating unnecessary CSS.

The Object syntax#

You can also define responsive values with breakpoint aliases in an object. Any undefined alias key will define the base, non-responsive value.

Let's say you have a Text that looks like this:

<Text fontSize="40px">This is a text</Text>

To make the fontSize responsive using the object syntax, here's what you need to do:

<Text fontSize={{ base: "24px", md: "40px", lg: "56px" }}>
  This is responsive text
</Text>

Remember, Chakra UI uses the min-width media query for responsive design. The breakpoints are: base = 0em, sm = 30em, md = 48em, lg = 62em, xl = 80em,, 2xl = 96em

Here's how to interpret this syntax fontSize={{ base: '24px', md: '40px', lg: '56px' }}:

• 24px: From 0em upwards
• 40px: From 48em upwards
• 56px: From 62em upwards

More Examples#

This works for every style prop in the theme specification, which means you can change the style of most properties at a given breakpoint.

<>
  <Box
    height={{
      base: "100%", // 0-48em
      md: "50%", // 48em-80em,
      xl: "25%", // 80em+
    }}
    bg="teal.400"
    width={[
      "100%", // 0-30em
      "50%", // 30em-48em
      "25%", // 48em-62em
      "15%", // 62em+
    ]}
  />
  {/* responsive font size */}
  <Box fontSize={["sm", "md", "lg", "xl"]}>Font Size</Box>
  {/* responsive margin */}
  <Box mt={[2, 4, 6, 8]} width="full" height="24px" bg="tomato" />
  {/* responsive padding */}
  <Box bg="papayawhip" p={[2, 4, 6, 8]}>
    Padding
  </Box>
</>

Under the hood#

This shortcut is an alternative to writing media queries out by hand. Given the following:

<Box width={[1, 1 / 2, 1 / 4]} />

It'll generate a CSS that looks like this

.Box {
  width: 100%;
}

@media screen and (min-width: 30em) {
  .Box {
    width: 50%;
  }
}

@media screen and (min-width: 48em) {
  .Box {
    width: 25%;
  }
}

The equivalent of this style if you passed it as an object.

Customizing Breakpoints#

In some scenarios, you might need to define custom breakpoints for your application. We recommended using common aliases like sm, md, lg, and xl.

To define custom breakpoints, just pass them as an object into the theme.

Note: Make sure you are using the same CSS unit for all of your breakpoints. Use all px or all em, don't mix them!

// 1. Import the utilities
import { extendTheme } from "@chakra-ui/react";

// 2. Update the breakpoints as key-value pairs
const breakpoints = {
  base: "0px",
  sm: "320px",
  md: "768px",
  lg: "960px",
  xl: "1200px",
  "2xl": "1536px",
};

// 3. Extend the theme
const theme = extendTheme({ breakpoints });

// 4. Now you can use the custom breakpoints
function Example() {
  return <Box width={{ base: "100%", sm: "50%", md: "25%" }} />;
}

Note: If you're using pixels as breakpoint values make sure to always provide a value for the 2xl breakpoint, which by its default pixels value is "1536px".

Demo#

Here's a simple example of a marketing page component that uses a stacked layout on small screens, and a side-by-side layout on larger screens (resize your browser to see it in action):

<Box p={4} display={{ md: "flex" }}>
  <Box flexShrink={0}>
    <Image
      borderRadius="lg"
      width={{ md: 40 }}
      src="https://bit.ly/2jYM25F"
      alt="Woman paying for a purchase"
    />
  </Box>
  <Box mt={{ base: 4, md: 0 }} ml={{ md: 6 }}>
    <Text
      fontWeight="bold"
      textTransform="uppercase"
      fontSize="sm"
      letterSpacing="wide"
      color="teal.600"
    >
      Marketing
    </Text>
    <Link
      mt={1}
      display="block"
      fontSize="lg"
      lineHeight="normal"
      fontWeight="semibold"
      href="#"
    >
      Finding customers for your new business
    </Link>
    <Text mt={2} color="gray.500">
      Getting a new business off the ground is a lot of hard work. Here are five
      ideas you can use to find your first customers.
    </Text>
  </Box>
</Box>