utilities - responsiveCss

View on GitHub

import { responsiveCss } from '@sky-uk/ui-core';

The following examples are for demonstration purposes only.

Due to a limitation of the react-live environment, which requires all code to be self-contained within the rendered component, responsiveCss is used within the Example function.

To ensure optimal performance and avoid unnecessary re-creation on every render, you should define styled-components using responsiveCss outside of your render method. This will ensure that the styles are only created once and reused across renders.

const Box = styled.div`
    ${responsiveCss(
      { padding: { xs: ‘8px’, xl: ‘32px’ } },
      ({ padding }) => css`
        padding: ${padding};
      `
    )}
    background: ${color(‘grey10’)};
  `;

  function Component() {
    return <Box>Padded box</Box>;
  }

See the styled-components docs for more information.

The responsiveCss utility generates responsive styled-components CSS from breakpoint-aware prop values. It automatically produces base styles and @media queries for each breakpoint where values change, using a mobile-first (min-width) approach.

This is the CSS-in-JS counterpart to the useResponsiveProps hook. Use responsiveCss when you need responsive behaviour handled entirely in styles (e.g. inside a styled component definition), rather than at the React render level.

When to use `responsiveCss` vs `useResponsiveProps`

	`responsiveCss`	`useResponsiveProps`
Runs in	CSS (`styled-components`)	React (hook)
Re-renders on resize	No — pure CSS media queries	Yes — listens to `matchMedia`
Best for	Visual / layout properties (padding, font-size, colour)	Conditional rendering, switching asset URLs

Basic usage

function Example() {
  const Box = styled.div`
    ${responsiveCss(
      { padding: { xs: '8px', md: '16px', xl: '32px' } },
      ({ padding }) => css`
        padding: ${padding};
      `
    )}
    background: ${color('grey10')};
  `;

  return <Box>Resize the viewport to see padding change</Box>;
}

With multiple props

Pass several responsive props at once. The renderCss callback receives all resolved values together, so you can use them in a single template.

function Example() {
  const Card = styled.div`
    ${responsiveCss(
      {
        padding: { xs: '8px', md: '16px', xl: '32px' },
        fontSize: { xs: '14px', lg: '18px' },
        background: { xs: '#e0e0e0', md: '#c0c0c0' },
      },
      ({ padding, fontSize, background }) => css`
        padding: ${padding};
        font-size: ${fontSize};
        background: ${background};
      `
    )}
  `;

  return <Card>Responsive card</Card>;
}

Mixing responsive and static props

Props that are not wrapped in a breakpoint object are treated as static values and remain constant across all breakpoints.

function Example() {
  const Box = styled.div`
    ${responsiveCss(
      {
        padding: { xs: '8px', lg: '24px' },
        color: 'red',
      },
      ({ padding, color }) => css`
        padding: ${padding};
        color: ${color};
      `
    )}
  `;

  return <Box>Static colour, responsive padding</Box>;
}

Using the fallback key

Instead of specifying an xs value, you can use fallback to set the base value. This is useful when the breakpoint object does not start at xs.

responsiveCss(
  { gap: { fallback: '8px', lg: '24px' } },
  ({ gap }) => css`
    gap: ${gap};
  `
);

API

`responsiveCss(props, renderCss)`

Parameter	Type	Description
`props`	`Record<string, ResponsiveValue<T>>`	An object of prop names to either a static value or a breakpoint object (e.g. `{ xs: …, md: … }`).
`renderCss`	`(resolved) => RuleSet`	A callback that receives the resolved values for the current breakpoint and returns a `css` template literal.