Widget Grid
Dashboard widgets you lift, drag and resize on a 6-column grid, with spring physics and full keyboard support.
Source: https://kokonutui.com/docs/cards/bento-grid
Installation
npx shadcn@latest add @kokonutui/bento-grid
Props
| Prop |
Type |
Default |
Description |
items? |
WidgetGridItem[] |
demo |
|
layout? |
WidgetLayoutItem[] |
|
Controlled order and spans. |
defaultLayout? |
WidgetLayoutItem[] |
|
Uncontrolled starting order and spans. |
onLayoutChange? |
(layout: WidgetLayoutItem[]) => void |
|
Called on every reorder or resize, including live moves while dragging. |
className? |
string |
|
Extra classes for the root element. |
rowHeight? |
number |
176 |
Height of one row in pixels. |
WidgetGridItem
| Field |
Type |
Description |
id |
string |
|
title |
string |
|
icon? |
ReactNode |
|
render |
(size: WidgetSize) => ReactNode |
Renders the widget body for the size its column span maps to. |
defaultSpan? |
number |
Span used when no layout is given. Defaults to 2. |
WidgetLayoutItem
| Field |
Type |
Description |
id |
string |
|
span |
number |
Width in columns of the 6-column grid (2 to 6). |
WidgetSize
type WidgetSize = "s" | "m" | "l";
Source
"use client";
/**
* @author: @dorianbaffier
* @description: Widget Grid
* @version: 3.0.0
* @date: 2026-10-14
* @license: MIT
* @website: https://kokonutui.com
* @github: https://github.com/kokonut-labs/kokonutui
*/
import {
Activity,
GripVertical,
HardDrive,
History,
NotebookPen,
TrendingUp,
Users,
} from "lucide-react";
import { AnimatePresence, motion } from "motion/react";
import {
type CSSProperties,
type FocusEvent,
type KeyboardEvent,
type MouseEvent,
type ReactNode,
type PointerEvent as ReactPointerEvent,
useCallback,
useEffect,
useId,
useLayoutEffect,
useMemo,
useRef,
useState,
} from "react";
import { cn } from "@/lib/utils";
/* -------------------------------------------------------------------------- */
/* Types */
/* -------------------------------------------------------------------------- */
export type WidgetSize = "s" | "m" | "l";
export interface WidgetGridItem {
id: string;
title: string;
icon?: ReactNode;
/** Renders the widget body for the size its column span maps to. */
render: (size: WidgetSize) => ReactNode;
/** Span used when no layout is given. Defaults to 2. */
defaultSpan?: number;
}
export interface WidgetLayoutItem {
id: string;
/** Width in columns of the 6-column grid (2 to 6). */
span: number;
}
export interface WidgetGridProps {
items?: WidgetGridItem[];
/** Controlled order and spans. */
layout?: WidgetLayoutItem[];
/** Uncontrolled starting order and spans. */
defaultLayout?: WidgetLayoutItem[];
/** Called on every reorder or resize, including live moves while dragging. */
onLayoutChange?: (layout: WidgetLayoutItem[]) => void;
className?: string;
/** Height of one row in pixels. */
rowHeight?: number;
}
/* -------------------------------------------------------------------------- */
/* Demo widgets */
/* -------------------------------------------------------------------------- */
const ICON = "size-3.5";
export const DEMO_WIDGETS: WidgetGridItem[] = [
{
id: "revenue",
title: "Revenue",
icon: <TrendingUp className={ICON} />,
defaultSpan: 2,
render: (size) => <RevenueWidget size={size} />,
},
{
id: "users",
title: "Active users",
icon: <Users className={ICON} />,
defaultSpan: 4,
render: (size) => <UsersWidget size={size} />,
},
{
id: "activity",
title: "Activity",
icon: <History className={ICON} />,
defaultSpan: 3,
render: (size) => <TimelineWidget size={size} />,
},
{
id: "notes",
title: "Notes",
icon: <NotebookPen className={ICON} />,
defaultSpan: 3,
render: (size) => <NotesWidget size={size} />,
},
{
id: "uptime",
title: "Uptime",
icon: <Activity className={ICON} />,
defaultSpan: 4,
render: (size) => <UptimeWidget size={size} />,
},
{
id: "storage",
title: "Storage",
icon: <HardDrive className={ICON} />,
defaultSpan: 2,
render: (size) => <StorageWidget size={size} />,
},
];
export default function WidgetGrid({
items = DEMO_WIDGETS,
layout,
defaultLayout,
onLayoutChange,
className,
rowHeight = 176,
}: WidgetGridProps) {
const instructionsId = useId();
const [innerLayout, setInnerLayout] = useState<WidgetLayoutItem[]>(() =>
normalizeLayout(defaultLayout ?? [], items)
);
const current = useMemo(
() => normalizeLayout(layout ?? innerLayout, items),
[layout, innerLayout, items]
);
const layoutKey = current.map((c) => `${c.id}:${c.span}`).join("|");
const itemsById = useMemo(
() => new Map(items.map((item) => [item.id, item])),
[items]
);
/* Rendering Logic ... */
}