Emotion grid system

A mobile-first responsive grid system built with @emotion/css.

Installation

Emotion and React are peer dependencies, so install them alongside the package:

pnpm add emotion-grid-system @emotion/css @emotion/react react

Basic Usage

To create a responsive layout, wrap your columns (Grid.Col) inside a row (Grid.Row), and the row inside a container (Grid.Container).

import { Grid } from "emotion-grid-system";

function Page() {
  return (
    <Grid.Container>
      <Grid.Row>
        <Grid.Col
          size={{
            initial: 4,
            md: 6,
            xl: 12,
          }}
        >
          Col
        </Grid.Col>
        <Grid.Col
          size={{
            initial: 4,
            md: 6,
            xl: 12,
          }}
        >
          Col
        </Grid.Col>
      </Grid.Row>
    </Grid.Container>
  );
}

export default Page;

Breakpoints and columns

The first breakpoint is named initial (there is no xs), and the number of columns changes per breakpoint:

| Breakpoint | Min width | Columns | | ---------- | -------------- | ------- | | initial | 0 | 4 | | sm | 40rem (640) | 8 | | md | 48rem (768) | 12 | | lg | 64rem (1024) | 12 | | xl | 80rem (1280) | 12 | | 2xl | 96rem (1536) | 12 |

size and offset are relative to the columns of that breakpoint, so size={{ initial: 2 }} is half the width on mobile (2 of 4) and size={{ md: 6 }} is half the width from md up (6 of 12).

Migrating from @mverissimoo/emotion-grid? Rename xs to initial. Unknown breakpoint keys are ignored and logged in development.

Customization

Any part of the theme can be overridden — partial themes are deep merged with the defaults, so you only declare what changes:

import { ThemeProvider } from "@emotion/react";

<ThemeProvider theme={{ grid: { gutter: { md: "1rem" } } }}>
  <App />
</ThemeProvider>;

TypeScript types for the grid key are shipped with the package (the Emotion Theme interface is augmented automatically).

SSR

useBreakpoint (and therefore Display.Visible, Display.Hidden and Display.ScreenClass) is built on useSyncExternalStore: on the server it resolves to the initial breakpoint and hydrates without mismatches.

To avoid the client-only flash on Visible/Hidden, use the CSS mode, which keeps the children in the DOM and toggles them with media queries:

<Display.Hidden media={["initial", "sm"]} mode="css">
  <Sidebar />
</Display.Hidden>

Development

The repository is managed by Vite+, which wraps the runtime, the package manager and the frontend tooling in a single vp CLI.

vp install        # install dependencies
vp check          # format, lint and type check
vp test           # run the test suite
vp pack           # build the package (ESM + CJS + types)
pnpm storybook    # docs and playground

Looking for docs

You can check here, guides and API reference.

Built with

• Emotion
• Storybook
• Vite+