Skip to content

SimpleGrid

Uniform-column grid driven by columns (a number or breakpoint map) and gap. The 90% path that doesn't need Grid's full template surface.

stable
since v0.1.0
3.61 kB
primitive
layout
grid

Preview

tsx

import { Box, SimpleGrid } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <SimpleGrid
      columns={{ base: 2, md: 4 }}
      gap="3"
      padding="4"
      background="bg.subtle"
      borderRadius="md"
    >
      <Box padding="3" background="bg.surface" borderRadius="sm">
        1
      </Box>
      <Box padding="3" background="bg.surface" borderRadius="sm">
        2
      </Box>
      <Box padding="3" background="bg.surface" borderRadius="sm">
        3
      </Box>
      <Box padding="3" background="bg.surface" borderRadius="sm">
        4
      </Box>
    </SimpleGrid>
  );
}

Responsive columns

Pass a breakpoint map to columns so the grid reflows naturally — the most common pattern is a 1-column phone layout that climbs to 4 columns on the widest viewports.

Preview

tsx

import { Box, SimpleGrid } from '@arshad-shah/cynosure-react';

const CARDS = ['Alpha', 'Beta', 'Gamma', 'Delta', 'Epsilon', 'Zeta'];

export default function Example() {
  return (
    <SimpleGrid
      columns={{ base: 1, sm: 2, lg: 3 }}
      gap="3"
      padding="4"
      background="bg.subtle"
      borderRadius="md"
    >
      {CARDS.map((label) => (
        <Box key={label} padding="3" background="bg.surface" borderRadius="sm">
          {label}
        </Box>
      ))}
    </SimpleGrid>
  );
}

`minChildWidth`

When the column count should be driven by space rather than by you, pass minChildWidth and let the grid pick the column count automatically. New columns appear whenever the container can fit another minChildWidth-wide track.

Preview

tsx

import { Box, SimpleGrid } from '@arshad-shah/cynosure-react';

const TILES = ['Aurora', 'Borealis', 'Cassiopeia', 'Draco', 'Eridanus', 'Fornax', 'Gemini'];

export default function Example() {
  return (
    <SimpleGrid minChildWidth="180px" gap="3" padding="4" background="bg.subtle" borderRadius="md">
      {TILES.map((label) => (
        <Box key={label} padding="3" background="bg.surface" borderRadius="sm">
          {label}
        </Box>
      ))}
    </SimpleGrid>
  );
}

API

PropTypeDefaultDescription

className

string

—

Additional class names appended after Cynosure's base classes.

style

CSSProperties

—

Inline style overrides merged last.

children

ReactNode

—

Grid children.

columns

Responsive<number>

—

Fixed column count — emits `repeat(N, minmax(0, 1fr))`. Ignored when `minChildWidth` is set.

minChildWidth

Responsive<SizeValue>

—

Minimum width each child should occupy before a new column is added. Emits `repeat(auto-fit, minmax(<minChildWidth>, 1fr))` for a fluid grid that reflows without breakpoints. Wins over `columns`.

gap

Responsive<SpaceToken>

—

Uniform gap in both axes.

columnGap

Responsive<SpaceToken>

—

Gap between columns. Overrides the column axis of `gap`.

rowGap

Responsive<SpaceToken>

—

Gap between rows. Overrides the row axis of `gap`.

padding

Responsive<SpaceToken>

—

Padding on all four sides. Token from the spacing scale.

paddingX

Responsive<SpaceToken>

—

Horizontal padding (left + right). Overrides `padding` on the X axis.

paddingY

Responsive<SpaceToken>

—

Vertical padding (top + bottom). Overrides `padding` on the Y axis.

paddingTop

Responsive<SpaceToken>

—

Padding on the top edge. Beats `padding` / `paddingY`.

paddingRight

Responsive<SpaceToken>

—

Padding on the right (inline-end in RTL) edge.

paddingBottom

Responsive<SpaceToken>

—

Padding on the bottom edge.

paddingLeft

Responsive<SpaceToken>

—

Padding on the left (inline-start in RTL) edge.

margin

Responsive<MarginValue>

—

Margin on all four sides. Accepts the spacing scale or `"auto"`.

marginX

Responsive<MarginValue>

—

Horizontal margin (left + right). Use `"auto"` to centre.

marginY

Responsive<MarginValue>

—

Vertical margin (top + bottom).

marginTop

Responsive<MarginValue>

—

Margin on the top edge.

marginRight

Responsive<MarginValue>

—

Margin on the right edge.

marginBottom

Responsive<MarginValue>

—

Margin on the bottom edge.

marginLeft

Responsive<MarginValue>

—

Margin on the left edge.

width

Responsive<SizeValue>

—

Element width. Accepts a `SpaceToken`, `LengthValue`, or named alias.

height

Responsive<SizeValue>

—

Element height. Accepts a `SpaceToken`, `LengthValue`, or named alias.

minWidth

Responsive<SizeValue>

—

Minimum width — useful for preventing flex children from collapsing.

maxWidth

Responsive<SizeValue>

—

Maximum width — `"prose"` caps to a comfortable reading measure.

minHeight

Responsive<SizeValue>

—

Minimum height.

maxHeight

Responsive<SizeValue>

—

Maximum height.

background

Responsive<ColorToken>

—

Background colour. Use a `ColorToken` like `"bg.surface"` for theme awareness.

color

Responsive<ColorToken>

—

Text colour. Inherits unless set.

borderColor

Responsive<ColorToken>

—

Border colour. Pair with `borderWidth` to make the border visible.

borderWidth

Responsive<BorderWidth>

—

Border thickness in scale steps.

borderStyle

Responsive<BorderStyle>

—

Border line style.

borderRadius

Responsive<RadiusToken>

—

Corner rounding token.

boxShadow

Responsive<ShadowToken>

—

Drop-shadow token from the elevation scale.

opacity

Responsive<number | `${number}`>

—

Opacity 0–1. Use sparingly — prefer surface tokens over translucency.

overflow

Responsive<Overflow>

—

How content that exceeds the box is handled.

overflowX

Responsive<Overflow>

—

Horizontal-axis overflow control. Overrides `overflow` for the X axis.

overflowY

Responsive<Overflow>

—

Vertical-axis overflow control.

display

Responsive<Display>

—

CSS `display` value. `"contents"` removes the element's box from layout.

position

Responsive<Position>

—

CSS `position`. Pair with `top`/`right`/`bottom`/`left` for placement.

top

Responsive<InsetValue>

—

Top inset (when positioned). Accepts a `SpaceToken`, `"auto"`, `"0"`, or `LengthValue`.

right

Responsive<InsetValue>

—

Right inset (when positioned).

bottom

Responsive<InsetValue>

—

Bottom inset (when positioned).

left

Responsive<InsetValue>

—

Left inset (when positioned).

zIndex

Responsive<ZIndexToken>

—

Stacking-context layer token (`"modal"`, `"tooltip"`, …).

gridColumn

Responsive<string>

—

Grid-column shorthand (e.g. `"1 / 3"`, `"span 2"`).

gridRow

Responsive<string>

—

Grid-row shorthand.

gridArea

Responsive<string>

—

Named grid area.

flex

Responsive<"1" | "none" | "auto" | "initial" | (string & {})>

—

Shorthand: `1 | auto | none | initial | <css>`. Resolves to `flex` on the child.

flexGrow

Responsive<number | `${number}`>

—

Grow factor inside a flex container.

flexShrink

Responsive<number | `${number}`>

—

Shrink factor inside a flex container.

flexBasis

Responsive<SizeValue | "content">

—

Initial main-axis size before grow/shrink.

alignSelf

Responsive<AlignSelf>

—

Override `align-items` for a single child.

justifySelf

Responsive<JustifySelf>

—

Override `justify-items` for a single child (grid).

order

Responsive<number | `${number}`>

—

Flex/grid child reorder index.

asChild

boolean

—

When `true`, renders the primitive's single React child via `Slot`, forwarding className/style/ref/event handlers onto it.

as

ElementType

"div"

Rendered intrinsic element or component.

ref

ForwardedRef<Element>

—

Recipes

Card grids: <SimpleGrid columns={{ base: 1, sm: 2, lg: 3 }} gap="4" /> covers most product / blog / team layouts.
Auto-flow gallery: <SimpleGrid minChildWidth="200px" gap="3" /> adapts to any container width without a media-query map.
For non-uniform columns or named areas, reach for Grid instead.