bento grid.md

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 ... */
}