Board

InstallCopy Anchor Link

pnpm exec vegastack-design verify board

pnpm dlx shadcn@4.21.0 add @vegastack/board

UsageCopy Anchor Link

Moves recheck current card and destination permissions at drop. Asynchronous moves are serialized so a rejected move cannot roll back another pending card.

import { Board } from "@/components/ui/board";
import { BoardCard } from "@/components/ui/board-card";

<Board
  aria-label="Tasks"
  columns={statuses.map((s) => ({
    id: s.id,
    title: s.label,
    items: tasksBy[s.id],
  }))}
  getItemId={(task) => task.id}
  getItemLabel={(task) => task.title}
  renderCard={(task) => (
    <BoardCard
      surface={false}
      title={task.title}
      due={task.dueAt}
      priority={task.priority}
    />
  )}
  onMove={({ id, to }) => api.moveTask(id, to.container, to.index)}
  onAdd={(status) => openCreate({ status })}
  addLabel="Add task"
/>;

The split is content/chrome: you render card content only — a BoardCard with surface={false} is the standard content — and the board owns the lanes, sticky headers, counts, the collapse strip, empty drop zones, skeletons, paging, the add button, the lifted card and the gap it lands in. onMove is the single move command for every input path: drag, keyboard and the card menu.

ScopeCopy Anchor Link

ExamplesCopy Anchor Link

Task boardCopy Anchor Link

The full board: BoardCard content, a full-width "+ Add task" right after each lane's last card (onAdd receives the lane's id, so the host's create form opens with that status filled in), per-card actions with a submenu, and an empty lane ("In review") that reads "Nothing here" with a content-width "+ Add task" as its action at rest, and "Drop here" while a card is dragged. The add button scrolls with the cards, after the loading tail when the lane pages.

Drag a card: it lifts with a shadow and a slight tilt, the cards around it slide to make room, and it settles into its slot. Near a lane's top or bottom edge the lane scrolls; near the board's side edges the board scrolls. On a touch screen, hold a card for a quarter of a second to pick it up (the device buzzes where it can); a swipe still scrolls. Under reduced motion the card still follows the pointer, without the tilt or the slides.

Header add and trailing contentCopy Anchor Link

addPlacement="header" moves each lane's add button into its header, an icon button beside the ⋯ menu whose accessible name and tooltip are addLabel. A column's icon leads its title (the status glyph of a status lane), and trailing renders after the last lane inside the sideways scroller — an "Add lane" button. Cards sit on a slightly raised surface.

Hidden lanes. hiddenColumns lists the lanes the host has hidden under a "Hidden columns" heading after the last lane, each with its icon and count; choosing one calls onShowColumn. A column marked hideable offers "Hide column" in its ⋯ menu, which calls onHideColumn — the host takes the lane out of columns and lists it in hiddenColumns. Each lane still pages on its own (loadMore), so a task board with per-lane keysets and hidden lanes is a Board.

Full heightCopy Anchor Link

height="fill" is the default: the board measures where it starts and runs its lanes to the bottom of the viewport (less fillOffset, the page's bottom padding). Cards scroll inside each lane and the page never scrolls. Lanes are 320px (columnWidth) with a 12px gap; the board scrolls sideways with a hidden scrollbar and fades at the edges that have more. A sideways pan — a trackpad swipe, Shift+wheel or a touch swipe — scrolls the board wherever it starts, over a lane or a card included; a lane body scrolls only vertically. Pass height="auto" to size lanes to their cards, or any CSS length.

Collapsed lanesCopy Anchor Link

Every lane header has a collapse icon button (tooltip "Collapse lane") left of its ⋯ menu; turn it off with collapsible={false}. The ⋯ menu holds only the lane's own actions from getColumnActions and hides when there are none. Each lane has a subtle top-to-bottom muted fade behind its cards, and cards keep their own surface; while a card is dragged over a lane, the fade gives way to a solid accent wash. A collapsed lane is a slim dashed strip with an expand icon and its count (tooltip "Expand lane"); activating it expands the lane. Control the set with collapsedColumns and onCollapsedChange to remember it. A lane declared defaultCollapsed is a terminal lane: it expands read-only.

Lanes keep their width (columnWidth, default 20rem) however many are collapsed: the space a collapsed lane frees stays empty instead of stretching the others, and a board with more lanes than fit scrolls sideways. The preview starts with two lanes collapsed.

Calm lanesCopy Anchor Link

Three opt-in props keep a board with sparse lanes quiet; a board without them behaves as before. emptyLane="compact" draws an empty lane as its header over a 48px dashed drop target, with a + that calls onAdd — never a tall "Nothing here" box. emptyLane="collapse" moves empty lanes into the Hidden columns list after the last lane: choosing one brings it back (compact), a card dragged onto it there lands in it, and a lane that a move empties stays put rather than vanishing under the pointer. noValueLane="last" puts the lane marked noValue ("No stage") after the others and lets it collapse even when the board is not collapsible.

A board loading its first data shows one skeleton for the whole load: with loading, lane shells (loadingLanes, 4 by default) with skeleton titles stand in for the lanes — no skeleton cards and no counts. A single lane still fetching its first cards shows no count until they arrive, never a "0" over skeletons. When lanes overflow sideways, both edges fade and carry a soft scroll shadow.

Server-gated movesCopy Anchor Link

Moves are optimistic: the card lands at once and shimmers while onMove's promise is pending. A rejection snaps it back, announces it, and raises an error toast (moveErrorToast sets its title, or false turns it off; the app mounts Toaster).

Locked lanes and auto heightCopy Anchor Link

A lane with droppable: false is never a target; its lockedReason shows in the lane when it is empty. With height="auto", columnMaxHeight caps each lane's card list.

Read-onlyCopy Anchor Link

readOnly turns every move off for the whole board and hides "+ Add" (as does a lane's own addable: false); cards still focus, open and follow their links. A defaultCollapsed lane expands read-only on its own.

Locked cardsCopy Anchor Link

canMoveItem is readOnly for one card — a view-only record on a board the user can otherwise edit. A card it answers false for keeps the default cursor, ignores pointer, touch and

Space pick-up and is not announced as draggable, but it still focuses, opens, keeps its ⋯ actions, and other cards move around it.

Lane and card labelsCopy Anchor Link

Every lane and card has a plain-text name, because the board speaks them. A string title names its lane on its own; a lane whose title is a node passes label (the board warns in development when it has to fall back to the id). getItemLabel names the cards — in their accessible name, their menu control ("Actions for Token audit") and every announcement.

Lane statesCopy Anchor Link

count is the lane's total when it has loaded only some cards ("Open, 14 tasks", through countLabel). Above 99 the lane shows "99+" (the bell's and the Inbox's cap) while its spoken name keeps the number; a host that counts only up to 100 says "more than 99" in countLabel. loading shows skeleton cards and marks the lane aria-busy. An empty lane shows the design-system Empty at rest: an Inbox icon and "Nothing here" (a locked lane adds its lockedReason). Change its copy with empty (icon, title, description, action); emptyState replaces it outright. With onAdd, the default empty state carries "+ Add" as its action; a custom emptyState keeps "+ Add" under it. While a card is dragged, an empty lane that accepts it shows "Drop here".

Cards as linksCopy Anchor Link

getItemHref makes each card a real link, rendered as <a> or as your router's link through itemLinkRender. A click follows it and a modifier click opens a new tab; a drag never follows it. Enter follows the link; Space still picks the card up. onCardActivate stays for cards without an href. onCardOpen opens every card's record in place — a peek: a link card's plain click (or Enter) calls it instead of following the link, while ⌘/Ctrl/Shift and middle clicks still open the link. activeItemId marks the open card (data-peek-active, the accent wash) and scrolls it into view as it changes. A card's ⋯ menu mounts the first time it is pointed at or pressed.

Paged lanes and card actionsCopy Anchor Link

A lane with more cards than it has loaded takes loadMore: the next batch loads as the lane's foot scrolls into view, with skeleton cards while it loads, through the shared LoadMore tail — no button; a failed batch shows its error with Try again. getItemActions(item) lists the card's own actions in its ⋯ menu (a card with none shows no ⋯); an action with items opens a submenu. The menu has no Move items — moves are the drag and the keyboard (Space, the arrows, Space).

On a phoneCopy Anchor Link

Below 768px the board shows one lane at a time at full width and snaps to each lane. Swipe to move between lanes, or tap a lane in the strip above, which shows each lane's count. The phone layout follows the viewport, not the preview frame: narrow the window or open this page on a phone to see it. To move a card to another lane, hold it, then drag it to the screen's edge: the board turns to the next lane.

API ReferenceCopy Anchor Link

ColumnCopy Anchor Link

AccessibilityCopy Anchor Link

• Every move has a keyboard path. Space picks the focused card up, the arrows move it (↑/↓ within its lane, ←/→ across lanes, RTL-aware), Space drops it and Escape puts it back. Nothing is committed until the drop, and each step is announced ("In review, position 2 of 3").
• A card locked by canMoveItem (or in a read-only lane) has no "Draggable card" role description, and Space does not pick it up; it still opens and keeps its menu.
• M opens the card's ⋯ menu of its own actions (it lists no Move items).
• Cards form one roving tab stop per board: ↑/↓ within a lane, ←/→ across, Home/End within the lane.
• Each lane is a region named by its label and total ("Open, 14 tasks"); a loading lane is aria-busy. The card's activator (a button, or a link) is a sibling of its content, so a BoardCard's done tick is its own control, never nested inside another.
• Moves, drops, cancels and rejections announce through one polite live region.
• No focus ring: the focused card takes the system's background tint (FOC-13).

Do / Don'tCopy Anchor Link