Nasaq
Actions

ViewToggle

Switches how a collection is shown (table, grid, board, list or calendar), with one view always pressed and optional persistence in localStorage.

View as MarkdownOpen in ChatGPTOpen in Claude
PreviewOpen ↗

Code

import { ViewToggle, type ViewMode } from "@fadymondy/nasaq/web";const [view, setView] = useState<ViewMode>("table");<ViewToggle views={["table", "grid"]} value={view} onValueChange={setView} storageKey="customers:view" />;

Actions · beta

Live examples and controls: ViewToggle in the lab.

Install

npx shadcn@latest add https://docs.nasaqui.com/r/view-toggle.json

A segmented control for picking how a collection is shown: a table, a grid of cards, a board, a list or a calendar. Exactly one view is pressed at a time. With storageKey the choice is remembered, so the page opens in the view the visitor left it in.

When to use

  • In a list page's toolbar, when the same records can be read as a table or as cards (or a board, a calendar).

When not to use

  • Switching between different content: use Tabs.
  • Toggling formatting or filters: use ToggleGroup directly.

Import

import { ViewToggle } from "@fadymondy/nasaq/web";
// inside this monorepo: "@nasaq/web"

Quick start

import { ViewToggle, type ViewMode } from "@fadymondy/nasaq/web";

const [view, setView] = useState<ViewMode>("table");

<ViewToggle views={["table", "grid"]} value={view} onValueChange={setView} storageKey="customers:view" />;

Anatomy

div [data-slot=view-toggle]
└─ ToggleGroup (segmented, aria-label "View")
   └─ Toggle [data-view=table|grid|board|list|calendar] (icon; label when `showLabels`, tooltip otherwise)

API

ViewToggle

PropTypeDefaultNotes
viewsViewMode[]["table", "grid"]The views offered, in order.
valueViewMode—Controlled view.
defaultValueViewModefirst of viewsUncontrolled start.
onValueChange(view: ViewMode) => void—Also called once after mount when a stored view is restored.
storageKeystring—Remembers the choice in localStorage. Read after mount, so SSR stays stable.
showLabelsbooleanfalseText beside each icon. Icon-only items get an aria-label and a tooltip.
labelsPartial<ViewToggleLabels>—Override the group name and view names.

Plus any <div> prop. ViewMode is "table" | "grid" | "board" | "list" | "calendar".

Examples

With labels

<ViewToggle views={["table", "grid", "list"]} showLabels />

Board and calendar for work items

<ViewToggle views={["board", "list", "calendar"]} defaultValue="board" storageKey="issues:view" onValueChange={setView} />

Accessibility

  • A Base UI toggle group: arrow keys move between views, Space and Enter press.
  • The group is named "View" / "طريقة العرض"; icon-only items carry an aria-label with the view's name.
  • Pressing the pressed view does nothing, so the group never ends up with no view.

RTL & i18n

View names ship in English and Arabic. Arrow keys follow the reading direction.

Styling & tokens

  • Inherits ToggleGroup's segmented look: bg-secondary track, bg-card pressed item, text-label.
  • Target a view with [data-slot=view-toggle] [data-view=grid].

Do / Don't

  • Do put it at the inline end of the list toolbar, next to filters.
  • Do use storageKey with a per-page key.
  • Don't offer views the page can't render well; two or three is typical.

toggle-group, data-table, kanban-board, page-header.

Lab

https://docs.nasaqui.com/?path=/docs/components-actions-view-toggle--docs

ToggleGroup

Pressed-state buttons grouped as a segmented control, single or multiple selection, plus a standalone Toggle.

Admin

Next Page

On this page

CodeInstallWhen to useWhen not to useImportQuick startAnatomyAPIViewToggleExamplesWith labelsBoard and calendar for work itemsAccessibilityRTL & i18nStyling & tokensDo / Don'tRelatedLab