Skip to main content

DashboardGrid Pro

DashboardGrid is a dashboard people arrange themselves. Widgets sit on a 12-column grid. In edit mode a widget drags with the others moving out of its way and springs into place, its corner resizes it in whole cells, ✕ removes it with Undo, and a gallery adds more in the first gap they fit. The grid measures its own width, so it shows 6 columns on tablets and one on phones, where a long press reorders. Each breakpoint keeps its own layout, and onLayoutChange gives them back for you to save.

Widget is the chrome inside each cell: a title, a period switch, a ⋯ menu with Refresh, Full screen, Duplicate and Remove, "Updated 3 min ago", and calm loading, empty and error states. It's part of Patine Pro and uses React Native core only.

import { DashboardGrid, Widget } from '@patine-ui/pro';
Loading…
<View style={{ width: '100%', gap: 16 }}>
  <View style={{ flexDirection: 'row', justifyContent: 'flex-end' }}>
    <Button variant={editing ? 'default' : 'outline'} onPress={() => setEditing(!editing)}>
      {editing ? 'Done' : 'Edit dashboard'}
    </Button>
  </View>
  <DashboardGrid
    layout={layout}
    onLayoutChange={setLayout}
    editing={editing}
    onEditingChange={setEditing}
    templates={TEMPLATES}
    getItemLabel={title}
    renderItem={renderItem}
    accessibilityLabel="Store dashboard"
  />
</View>

Try it: press Edit dashboard, drag a widget onto another, pull a corner to resize, remove one and press Undo, or tab to a widget and use the arrow keys.

Layouts and saving​

layout is the widest breakpoint's arrangement, in cells: { id, x, y, w, h }, the shape react-grid-layout uses. The narrower ones are worked out from it (widgets keep their order and stack), until someone arranges one by hand. onLayoutChange fires after every move, resize, add, duplicate, remove or undo with the widest layout, every hand-made one in layouts, and the current breakpoint. Save both and pass them back to restore the dashboard.

const [saved, setSaved] = useStoredState('dashboard', { layout: DEFAULT_LAYOUT, layouts: {} });

<DashboardGrid
layout={saved.layout}
layouts={saved.layouts}
onLayoutChange={(layout, layouts) => setSaved({ layout, layouts })}
renderItem={renderItem}
/>;

For a grid that keeps its own state, pass defaultLayout instead. minW, maxW, minH and maxH bound a widget's size, and static: true pins it: it can't be dragged, resized or pushed, and the others flow around it.

columns, breakpoints, rowHeight and gap change the grid itself: by default 12, 6 and 1 columns, starting at 1024 and 640 points of the grid's own width, with 56-point rows.

Adding widgets​

Pass templates and edit mode shows an Add widget tile that opens a gallery, grouped by category. A pick goes in the first gap it fits, and its type becomes the new item's type, so renderItem knows what to draw. To open the gallery from your own header, control it with galleryOpen and onGalleryOpenChange. onAdd and onRemove tell you which widget came or went.

Widget​

Widget draws the card. Its children can be a function of the content's size, so a chart fills whatever space the cell has after a resize.

Loading…
<Widget
  style={{ width: '100%', maxWidth: 520, height: 300 }}
  title="Visitors"
  subtitle="Unique, per day"
  period={{
    value: period,
    onValueChange: setPeriod,
    options: [
      { label: '7 days', value: '7d' },
      { label: '14 days', value: '14d' },
    ],
  }}
  onRefresh={() => {}}
  updatedAt={Date.now() - 120000}
>
  {({ height }) => (
    <LineChart data={DAYS} xKey="day" series={[{ key: 'visitors', label: 'Visitors' }]} height={Math.max(120, height)} accessibilityLabel="Visitors per day" />
  )}
</Widget>

Inside a DashboardGrid the ⋯ menu adds Full screen, Duplicate and Remove by itself. actions puts your own items first, and useDashboardItem() gives custom widgets the same item, edit state and actions.

Loading, empty and error​

loading shows a skeleton (a chart's shape, or your skeleton), empty a calm "No data for this period", and error a message with Try again that calls onRetry. The widget keeps its title and size in every state, so the dashboard doesn't jump while data arrives.

Loading…
<View style={{ width: '100%', gap: 16 }}>
  <Widget style={{ height: 200 }} title="Revenue" loading />
  <Widget style={{ height: 200 }} title="Refunds" empty />
  <Widget style={{ height: 200 }} title="Signups" error="The signups service timed out." onRetry={() => {}} />
</View>

Number ticker​

NumberTicker counts to each new value in tabular digits, so a KPI that updates doesn't wobble. Screen readers hear only the final value, and it jumps straight there with reduce motion on.

<NumberTicker value={visitors} format={(v) => Math.round(v).toLocaleString()} size="3xl" weight="semibold" />

Designs​

  • Patine: soft cards with a hairline and a low shadow; the drop spot is a dashed outline.
  • iOS: grouped panels on the surface color, no border, as iOS widgets.
  • Material: Material 3 filled (tonal) cards and a soft drop spot.
  • Web: bordered panels with a divided header, as Grafana and Datadog.

Accessibility​

  • The grid is a list and each widget a group named by its title. In edit mode each widget is a button that says where it is and how big ("Revenue, column 1, row 1, 4 by 3").
  • On the web, the focused widget moves with the arrow keys, resizes with Shift and the arrow keys, and Delete removes it.
  • Screen readers get Move left, right, up and down, Wider, Narrower, Taller and Shorter as actions, so nothing needs a drag.
  • Removing announces "Revenue removed" with an Undo button. Loading widgets are marked busy, and errors are alerts.
  • Lifting, settling and the number ticker follow the OS reduce-motion setting. Touch targets are 44 points.

Props​

DashboardGrid​

PropTypeDefault
renderItem(item, { editing, breakpoint, fullScreen }) => ReactNode
layout, defaultLayoutGridItem[]: { id, type?, x, y, w, h, minW?, maxW?, minH?, maxH?, static? }
layouts, defaultLayouts{ compact?, medium?, expanded? }Worked out from layout
onLayoutChange(layout, layouts, breakpoint) => void
editing, defaultEditing, onEditingChangebooleanfalse
templates{ type, title, description?, icon?, category?, w, h, minW?, maxW?, minH?, maxH? }[]None: no gallery
galleryOpen, onGalleryOpenChangeboolean
onAdd(item, template) => void
onRemove(item) => void
getItemLabel(item) => stringIts template's title, or its id
columns{ compact?, medium?, expanded? }1, 6, 12
breakpoints{ medium?, expanded? }, in points of the grid's width640, 1024
rowHeightnumber56
gapnumberThe theme's spacing.lg
rtlbooleanThe app's direction
labelsPartial<DashboardLabels>English
accessibilityLabelstring'Dashboard'

Widget​

PropTypeDefault
titlestring
subtitlestring
iconIconName
period{ value, options: { label, value }[], onValueChange }
onRefresh() => void, adds Refresh to the menu
actions{ label, icon?, onPress, destructive? }[]
loading, skeletonboolean, ReactNodeA chart's shape
error, onRetrystring | boolean, () => void
empty, emptyTitle, emptyDescriptionboolean, string"No data for this period"
updatedAt, nowDate | string | number, Date
headerRight, footerReactNode
paddedbooleantrue
childrenReactNode or ({ width, height }) => ReactNode

Also exported: NumberTicker, useNumberTicker, useDashboardItem, the layout helpers addItem, removeItem, moveItem, resizeItem, compactLayout, deriveLayout, layoutFor, breakpointFor, the constants GRID_COLUMNS, GRID_BREAKPOINTS, DASHBOARD_LABELS, and the types GridItem, GridLayouts, GridBreakpoint, WidgetTemplate, WidgetProps.