Sponsor

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 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, here's what it looks like:

const breakpoints = {
  sm: "30em",
  md: "48em",
  lg: "62em",
  xl: "80em",
}

const breakpoints = {
  sm: "30em",
  md: "48em",
  lg: "62em",
  xl: "80em",
}

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

The Array syntax#

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

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

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

<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, 560]}>
  This is a box
</Box>

<Box bg="red.200" w={[300, 400, 560]}>
  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

// This is the default breakpoint
const breakpoints = { sm: "30em", md: "48em", lg: "62em", xl: "80em" }

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

// This is the default breakpoint
const breakpoints = { sm: "30em", md: "48em", lg: "62em", xl: "80em" }
// Internally, we transform to this
const breakpoints = ["0em", "30em", "48em", "62em", "80em"]

Here's how to interpret this syntax:

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 Box that looks like this:

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

<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>

<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: sm = 30em, md = 48em, lg = 62em, xl = 80em

Here's how to interpret this syntax:

base: From 0em upwards
md: From 48em upwards
lg: 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>
</>

<>
  <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]} />

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

It'll generate a CSS that looks like this

.Box {
  width: 100%;
}

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

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

.Box {
  width: 100%;
}
@media screen and (min-width: 40em) {
  .Box {
    width: 50%;
  }
}
@media screen and (min-width: 52em) {
  .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, install @chakra-ui/theme-tools, and use the createBreakpoints utility we provide.

Note: Ensure the css unit of your breakpoints are the same. Use all px or all em, don't mix them.

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

// 2. Update the breakpoints as key-value pairs
const breakpoints = createBreakpoints({
  sm: "320px",
  md: "768px",
  lg: "960px",
  xl: "1200px",
})

// 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%" }} />
}

// 1. Import the utilities
import { extendTheme } from "@chakra-ui/react"
import { createBreakpoints } from "@chakra-ui/theme-tools"
// 2. Update the breakpoints as key-value pairs
const breakpoints = createBreakpoints({
  sm: "320px",
  md: "768px",
  lg: "960px",
  xl: "1200px",
})
// 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%" }} />
}

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):

Marketing

Finding customers for your new business

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.

<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>

<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>

Editable Example

Edit this page