Grid

A responsive layout on twelve columns. GridContainer sets the column count and the gutters; Grid says how many columns a cell takes.

import { Grid, GridContainer } from 'neba';

<GridContainer spacing={3}>
  <Grid span={{ xs: 12, md: 8 }}>Body</Grid>
  <Grid span={{ xs: 12, md: 4 }}>Sidebar</Grid>
</GridContainer>;

GridContainer draws no surface, so it has no variant, color or elevation. Wrap it in a Box or a Card when the sheet is wanted.

Props

GridContainer

Prop	Type	Default	Description
columns	number | Partial<Record<NebaBreakpoint, number>>	12	How many columns a row divides into. Every span and offset inside is read against this number
spacing	number | Partial<Record<NebaBreakpoint, number>>	2	The gutter between items, on Tailwind's spacing scale: 4 is 1rem. Fractions are allowed: 1.5 is 0.375rem
rowSpacing	number | Partial<Record<NebaBreakpoint, number>>	spacing	The gutter between rows only
columnSpacing	number | Partial<Record<NebaBreakpoint, number>>	spacing	The gutter between columns only
justifyContent	'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch'	—	How a row distributes the space its items did not use. A prop of its own, not something to reach for sx or className for
alignItems	'start' | 'center' | 'end' | 'stretch' | 'baseline'	'stretch'	How items sit across the row. The default stretches, so a row of cards is a row of one height
alignContent	'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly' | 'stretch'	—	Where the rows sit when the grid is shorter than the box holding it. Only visible on a container with a height of its own
wrap	boolean	true	Whether a row that runs out of columns continues on the next one. Off gives one overflowing row, which is what a scrolling strip wants
padded	boolean	true	Inner padding. Turn it off when the grid already sits inside something that pads: a Container, a Card, another grid
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The padding's scale. As on Box it never touches a height or the type scale, and it is not the gutter: that is spacing
densityshared	'default' | 'compact'	'default'	Padding only
render	useRender.RenderProp	—	Renders something other than a div (<section />). Base UI's own escape hatch
children	ReactNode	—	The Grid items

Grid

Prop	Type	Default	Description
span	GridSpan | Partial<Record<NebaBreakpoint, GridSpan>>	a full row	How many of the container's columns the item takes. Per-breakpoint as { xs: 12, md: 6 }. A span wider than the row is clamped to the row rather than overflowing. 'auto' is as wide as the contents and 'grow' takes the space the row has left
offset	number | Partial<Record<NebaBreakpoint, number>>	0	Columns left empty ahead of the item: space pushed in before it, not an absolute position counted from the start of the row
alignSelf	'auto' | 'start' | 'center' | 'end' | 'stretch' | 'baseline'	—	Overrides the row's alignItems for this item alone
render	useRender.RenderProp	—	Renders something other than a div (<li />). Base UI's own escape hatch
children	ReactNode	—	What the cell holds

Both pass every native <div> attribute straight through.

Examples

span

span is read against the container's column count. On the default twelve, span={6} is a half; with columns={24} the same 6 is a quarter.

The width is (100% + gutter) × span / columns − gutter, so twelve span={1} cells and one span={12} end on exactly the same pixel.

import { Box, Grid, GridContainer } from 'neba';

const ROWS = [[12], [6, 6], [4, 4, 4], [3, 3, 3, 3], [8, 4]];

export default function GridSpans() {
  return (
    <div className="flex flex-col gap-2">
      {ROWS.map((row, index) => (
        <GridContainer key={index} padded={false}>
          {row.map((span, cell) => (
            <Grid key={cell} span={span}>
              <Box size="sm" className="text-center">
                {span}
              </Box>
            </Grid>
          ))}
        </GridContainer>
      ))}
    </div>
  );
}

auto · grow

Two widths are not a share of twelve. span="auto" is as wide as what is in the cell — an avatar, a chip, a button at the end of a row — and span="grow" is that plus everything the row has left over, which is how a title sits between the two.

Both mix with numbers in one responsive map — the contents' width on a phone, a third of the row from 48rem up:

<Grid span={{ xs: 'auto', md: 4 }}>Reference</Grid>

import { Avatar, Box, Button, Chip, Grid, GridContainer, Typography } from 'neba';

/**
 * The two widths a column count cannot reach: `auto` is as wide as what is in
 * the cell, and `grow` is that plus whatever the row has left over.
 */
export default function GridAutoGrow() {
  return (
    <div className="flex flex-col gap-3">
      <GridContainer spacing={2} padded={false} alignItems="center" wrap={false}>
        <Grid span="auto">
          <Avatar name="Rhea Patel" size="sm" />
        </Grid>
        <Grid span="grow" className="min-w-0">
          <Typography level="body" className="truncate">
            Rhea Patel opened a pull request
          </Typography>
        </Grid>
        <Grid span="auto">
          <Chip size="sm" color="success">
            Ready
          </Chip>
        </Grid>
        <Grid span="auto">
          <Button size="sm" variant="outline">
            Review
          </Button>
        </Grid>
      </GridContainer>

      {/* A keyword and a number in one map: the contents' width on a phone,
          a third of the row from 48rem up. */}
      <GridContainer spacing={2} padded={false}>
        <Grid span={{ xs: 'auto', md: 4 }}>
          <Box size="sm" className="text-center">
            auto, then 4
          </Box>
        </Grid>
        <Grid span={{ xs: 'grow', md: 8 }}>
          <Box size="sm" className="text-center">
            grow, then 8
          </Box>
        </Grid>
      </GridContainer>
    </div>
  );
}

breakpoints

Give span an object and it uses a different value per width. Every entry applies from its own breakpoint up (it is a floor, not a band), which is what makes two of them enough to describe a whole layout.

The widths are Tailwind's own defaults: sm 40rem · md 48rem · lg 64rem · xl 80rem. xs is 0, the value with no media query around it, so a grid and a md: utility change at the same moment.

columns · spacing · rowSpacing · columnSpacing · offset all take responsive values the same way.

import { Box, Grid, GridContainer } from 'neba';

/** Resize the window: four rows, then two, then one. */
export default function GridResponsive() {
  return (
    <GridContainer spacing={2} padded={false}>
      {['Overview', 'Traffic', 'Revenue', 'Errors'].map((label) => (
        <Grid key={label} span={{ xs: 12, sm: 6, lg: 3 }}>
          <Box className="text-center">{label}</Box>
        </Grid>
      ))}
    </GridContainer>
  );
}

spacing · rowSpacing · columnSpacing

spacing is on Tailwind's spacing scale. spacing={4} is 1rem, the same length as gap-4 or Box's p-4. Fractions are allowed, so spacing={1.5} is 0.375rem.

rowSpacing and columnSpacing each override one axis.

import { Box, Grid, GridContainer } from 'neba';

export default function GridSpacing() {
  return (
    <div className="flex flex-col gap-6">
      {/* One number sets both gutters. Fractions are allowed. */}
      {[0, 1.5, 4].map((spacing) => (
        <GridContainer key={spacing} spacing={spacing} padded={false}>
          {[0, 1, 2, 3].map((cell) => (
            <Grid key={cell} span={3}>
              <Box size="sm" className="text-center">
                spacing {spacing}
              </Box>
            </Grid>
          ))}
        </GridContainer>
      ))}

      {/* Or one per axis: tight columns, generous rows. */}
      <GridContainer columnSpacing={1} rowSpacing={6} padded={false}>
        {[0, 1, 2, 3, 4, 5].map((cell) => (
          <Grid key={cell} span={4}>
            <Box size="sm" className="text-center">
              1 / 6
            </Box>
          </Grid>
        ))}
      </GridContainer>
    </div>
  );
}

columns

The column count. Twelve is the default, but it does not divide by five, so values like 24 are useful. Every span and offset beneath the container is read against this number. A span wider than the row is clamped to the row rather than overflowing.

import { Box, Grid, GridContainer } from 'neba';

export default function GridColumns() {
  return (
    <div className="flex flex-col gap-6">
      {/* Twelve does not divide by five. Fifteen does. */}
      <GridContainer columns={15} spacing={2} padded={false}>
        {[0, 1, 2, 3, 4].map((cell) => (
          <Grid key={cell} span={3}>
            <Box size="sm" className="text-center">
              3 / 15
            </Box>
          </Grid>
        ))}
      </GridContainer>

      {/* A finer grid for a layout that needs seven-eighths of a row. */}
      <GridContainer columns={24} spacing={2} padded={false}>
        <Grid span={21}>
          <Box size="sm" className="text-center">
            21 / 24
          </Box>
        </Grid>
        <Grid span={3}>
          <Box size="sm" className="text-center">
            3
          </Box>
        </Grid>
      </GridContainer>
    </div>
  );
}

offset

Empty columns pushed in ahead of the item: space inserted in front of it rather than an absolute position counted from the start of the row. After an item that already took columns, the offset pushes on from there.

import { Box, Grid, GridContainer } from 'neba';

export default function GridOffset() {
  return (
    <div className="flex flex-col gap-2">
      {/* The middle third: four columns in, four columns wide. */}
      <GridContainer padded={false}>
        <Grid span={4} offset={4}>
          <Box size="sm" className="text-center">
            span 4, offset 4
          </Box>
        </Grid>
      </GridContainer>

      {/* Pushed to the end of the row. */}
      <GridContainer padded={false}>
        <Grid span={3} offset={9}>
          <Box size="sm" className="text-center">
            span 3, offset 9
          </Box>
        </Grid>
      </GridContainer>

      {/* An offset is space pushed in ahead of the item, so the gap here is
          between the two cells rather than measured from the start of the row. */}
      <GridContainer padded={false}>
        <Grid span={3}>
          <Box size="sm" className="text-center">
            span 3
          </Box>
        </Grid>
        <Grid span={3} offset={3}>
          <Box size="sm" className="text-center">
            span 3, offset 3
          </Box>
        </Grid>
      </GridContainer>
    </div>
  );
}

justifyContent · alignItems · alignContent · alignSelf

Alignment is set through props rather than a className. The first three live on GridContainer, alignSelf on Grid.

The values are start / center / end, which flip under RTL. Distribution values like space-between keep their CSS spelling.

import { Box, Grid, GridContainer } from 'neba';

export default function GridAlignment() {
  return (
    <div className="flex flex-col gap-6">
      {/* Three columns in a twelve-column row leave three spare. justifyContent
          decides where the slack goes — no sx, no className. */}
      {(['start', 'center', 'end', 'space-between'] as const).map((justify) => (
        <GridContainer key={justify} justifyContent={justify} padded={false}>
          {[0, 1, 2].map((cell) => (
            <Grid key={cell} span={3}>
              <Box size="sm" className="text-center">
                {justify}
              </Box>
            </Grid>
          ))}
        </GridContainer>
      ))}

      {/* Items are the same height as their row by default; alignItems opts out,
          and alignSelf lets one item disagree with the rest. */}
      <GridContainer alignItems="center" padded={false}>
        <Grid span={4}>
          <Box size="sm" className="h-20 text-center">
            tall
          </Box>
        </Grid>
        <Grid span={4}>
          <Box size="sm" className="text-center">
            centred
          </Box>
        </Grid>
        <Grid span={4} alignSelf="end">
          <Box size="sm" className="text-center">
            alignSelf end
          </Box>
        </Grid>
      </GridContainer>
    </div>
  );
}

padded

spacing is the space between items; padded is the padding around the grid. It defaults to true, so turn it off inside a Container, a Card or another grid.

size and density set how much.

import { Box, Grid, GridContainer } from 'neba';

export default function GridPadding() {
  return (
    <div className="flex flex-col gap-4">
      {/* The default: padded on the size scale, so the grid does not run into
          whatever is around it. */}
      <Box padded={false}>
        <GridContainer size="md">
          {[0, 1, 2].map((cell) => (
            <Grid key={cell} span={4}>
              <Box size="sm" variant="solid" className="text-center">
                padded
              </Box>
            </Grid>
          ))}
        </GridContainer>
      </Box>

      {/* Off, for a grid already inside something that pads — a Card, a
          Container, another grid. */}
      <Box padded={false}>
        <GridContainer padded={false}>
          {[0, 1, 2].map((cell) => (
            <Grid key={cell} span={4}>
              <Box size="sm" variant="solid" className="text-center">
                padded={'{false}'}
              </Box>
            </Grid>
          ))}
        </GridContainer>
      </Box>
    </div>
  );
}

Nesting

A grid inside a grid is a GridContainer inside a Grid. The inner grid re-divides the width its cell was given, so span={6} in there is half of a half.

import { Box, Grid, GridContainer } from 'neba';

/**
 * A grid inside a grid is a `GridContainer` inside a `Grid`, never a `Grid`
 * that is also a container. The inner grid re-divides the width its cell was
 * given, so `span={6}` in here is half of a half.
 */
export default function GridNested() {
  return (
    <GridContainer spacing={2} padded={false}>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Box padded={false} className="p-2">
          <GridContainer spacing={1} padded={false}>
            <Grid span={6}>
              <Box size="xs" variant="solid" className="text-center">
                6
              </Box>
            </Grid>
            <Grid span={6}>
              <Box size="xs" variant="solid" className="text-center">
                6
              </Box>
            </Grid>
            <Grid span={12}>
              <Box size="xs" variant="solid" className="text-center">
                12
              </Box>
            </Grid>
          </GridContainer>
        </Box>
      </Grid>
      <Grid span={{ xs: 12, sm: 6 }}>
        <Box className="h-full">The other half, undivided</Box>
      </Grid>
    </GridContainer>
  );
}