Dashboard grid

Pro

Tiles in as many columns as fit: each column at least minTileWidth wide, the columns sharing what is left. A narrow container (a side panel, a phone) gets one column, a wide one as many as fit, with no breakpoints to set; a tile is never narrower than minTileWidth unless the grid itself is. Put DashboardGridItem around a tile that should span more than one column.

Markdown

Version 5.2.0· other versions

This page is for 5.2.0, the current release. An earlier release’s page is the Markdown that release published, so the docs match the version you have installed (candor-lock.json records it).

Not in the docs of 1.3.0, 1.4.0, 1.5.0, 1.5.1, 1.6.0, 1.7.0, 1.8.0, 1.8.1, 1.9.0, 1.9.1, 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.5.1, 2.6.0, 2.6.1, 2.6.2, 2.7.0, 2.8.0, 2.9.0, 2.10.0, 3.0.0, 4.0.0, 4.0.1, 4.0.2 and 4.1.0: the page came later, or had another name then.

Docs pages weren’t kept for 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0 and 1.2.1: they are kept from 1.3.0 on, and before that only llms.txt was published.

Preview

Install

With the Candor CLI

First time? Get started sets up the registry and theme. Or with shadcn directly: npx shadcn@latest add @candor/dashboard-grid

Brings in: stack, tokens, utils · npm: @base-ui/react@^1.9.0

Usage

TSX · The example above

"use client"

import { DashboardGrid, DashboardGridItem } from "@/components/candor/dashboard-grid"
import { StatCard } from "@/components/candor/stat-card"

// Three tiles of different spans. Narrow the window: the wide tile takes the columns there are.
export default function Example() {
  return (
    <DashboardGrid minTileWidth={200} className="w-full">
      <DashboardGridItem span={2}>
        <StatCard kpi={{ label: "Runs this week", value: 1284, delta: { value: 112, vs: "last week", good: "up" } }} />
      </DashboardGridItem>
      <StatCard kpi={{ label: "Failed runs", value: 17 }} />
      <DashboardGridItem span="full">
        <StatCard kpi={{ label: "Cost this month", value: null, missing: "Needs billing access, which isn’t connected." }} />
      </DashboardGridItem>
    </DashboardGrid>
  )
}

<DashboardGrid>

Prop	Type	Default	Description
minTileWidth	`number \| undefined`	280	The narrowest a tile may be, in pixels. Default 280. The grid fits as many columns of at least this width as it can.
gap	`StackGap \| undefined`	4	The space between tiles, a step of the spacing scale that follows `data-density`. Default `4`.
render	`useRender.RenderProp \| undefined`	—	The element to draw instead of a `<div>`: `render={<section aria-label="Usage" />}`.
className	`string \| undefined`	—	Classes for the element, applied last, so they win over the props.
style	`React.CSSProperties \| undefined`	—	Styles for the element, applied after the grid's own.
children	`React.ReactNode \| undefined`	—	The tiles.

Also takes the props of React.ComponentProps<"div">.

<DashboardGridItem>

A tile that spans more than one column of a DashboardGrid. The span is clamped to the columns there are, so a two-column tile in a one-column grid takes the one column rather than overflowing. Until the grid has measured itself (a server render), a spanning tile takes one column; full always spans the row.

Prop	Type	Default	Description
span	`1 \| 2 \| 3 \| 4 \| "full" \| undefined`	1	How many columns the tile takes, at most the grid's columns; `full` takes the whole row. Default 1.
render	`useRender.RenderProp \| undefined`	—	The element to draw instead of a `<div>`: `render={<section />}`.
className	`string \| undefined`	—	Classes for the element, applied last, so they win over the props.
style	`React.CSSProperties \| undefined`	—	Styles for the element; the span's `grid-column` is set before them.
children	`React.ReactNode \| undefined`	—	The tile.

Also takes the props of React.ComponentProps<"div">.

Functions

gridColumns(width: number, minTile: number, gap: number)

How many columns of at least minTile pixels, gap apart, fit in width pixels: never fewer than one. The same sum the grid's repeat(auto-fit, minmax(min(minTile, 100%), 1fr)) does.