Skip to content
Shaken UI
Sign in

Sheet

Save

A side panel that slides in from any edge of the screen for settings and detail views, built on Base UI Drawer so it traps focus like a dialog and can be swiped away on touch.

Category
Overlays
Version
0.1.0
Frameworks
Next.js, Vite + React
Styling
Tailwind CSS v4

Preview

Sheet preview

Installation

npx @shakenui/cli add sheet

Review the plan first. A dry run lists every file and package without changing anything:

npx @shakenui/cli add sheet --dry-run

Usage

sheet-example.tsx
"use client";

import { useState } from "react";
import { Button } from "@/components/shaken/ui/button";
import {
  Sheet,
  SheetBody,
  SheetClose,
  SheetContent,
  SheetDescription,
  SheetFooter,
  SheetHeader,
  type SheetSide,
  SheetTitle,
} from "@/components/shaken/ui/sheet";

const sides: SheetSide[] = ["left", "top", "bottom", "right"];

const rules = [
  { id: "deploys", label: "Production deploys", detail: "Ask before the agent deploys to production.", on: true },
  { id: "secrets", label: "Secrets and keys", detail: "Ask before reading or rotating environment secrets.", on: true },
  { id: "migrations", label: "Database migrations", detail: "Ask before running a migration against any database.", on: true },
  { id: "deps", label: "New dependencies", detail: "Ask before adding a package to package.json.", on: false },
];

export default function SheetExample() {
  const [side, setSide] = useState<SheetSide>("right");
  const [open, setOpen] = useState(false);

  return (
    <div className="flex flex-wrap items-center justify-center gap-2">
      {sides.map((edge) => (
        <Button
          key={edge}
          variant="secondary"
          onClick={() => {
            setSide(edge);
            setOpen(true);
          }}
        >
          Open {edge}
        </Button>
      ))}

      <Sheet side={side} open={open} onOpenChange={setOpen}>
        <SheetContent>
          <SheetHeader>
            <SheetTitle>Approval rules</SheetTitle>
            <SheetDescription>Choose which actions pause the agent until someone on your team approves them.</SheetDescription>
          </SheetHeader>
          <SheetBody>
            <ul className="divide-y divide-zinc-950/[0.07] rounded-lg border border-zinc-950/[0.07] dark:divide-white/[0.08] dark:border-white/[0.08]">
              {rules.map((rule) => (
                <li key={rule.id}>
                  <label className="flex cursor-pointer items-start gap-3 px-3 py-3">
                    <input
                      type="checkbox"
                      defaultChecked={rule.on}
                      className="mt-0.5 size-4 shrink-0 accent-zinc-950 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500 dark:accent-white"
                    />
                    <span className="grid gap-0.5">
                      <span className="font-medium">{rule.label}</span>
                      <span className="text-zinc-600 dark:text-zinc-400">{rule.detail}</span>
                    </span>
                  </label>
                </li>
              ))}
            </ul>
            <p className="mt-4 text-xs text-zinc-500">Changes apply to runs that start after you save.</p>
          </SheetBody>
          <SheetFooter>
            <SheetClose render={<Button variant="secondary" />}>Cancel</SheetClose>
            <SheetClose render={<Button />}>Save rules</SheetClose>
          </SheetFooter>
        </SheetContent>
      </Sheet>
    </div>
  );
}

API

PropTypeDefaultDescription
Sheet side"top" | "right" | "bottom" | "left""right"Edge the panel slides in from. Swiping toward that edge dismisses it.
Sheet open / defaultOpen / onOpenChangeboolean / boolean / (open, details) => void—Root state. Leave open unset for an uncontrolled sheet.
Sheet modalboolean | "trap-focus"trueTraps focus, locks page scroll, and blocks outside pointer interaction.
SheetTrigger / SheetCloseBase UI Drawer.Trigger / Drawer.Close props—Unstyled buttons that open and close the sheet. Pass className, or render={<Button />}.
SheetContent size"sm" | "md" | "lg""md"Width of a left or right sheet: 20rem, 24rem, or 32rem, capped at the screen width minus 3rem.
SheetContent showCloseButton / closeLabelboolean / stringtrue / "Close"Corner icon button that closes the sheet, and its accessible name.
SheetHeader / SheetBody / SheetFooterdiv / Base UI Drawer.Content / div props—Layout: the header and footer stay fixed while the body scrolls. The footer is a band under a divider.
SheetTitle / SheetDescriptionBase UI Title / Description props—Heading and supporting text, wired to aria-labelledby and aria-describedby.

Accessibility

  • The panel has role="dialog" and aria-modal, named by SheetTitle and described by SheetDescription.
  • Opening moves focus into the sheet and traps Tab inside it; closing returns focus to the trigger.
  • Escape and a click on the backdrop close the sheet; swiping is an extra way to dismiss, never the only one.
  • The corner close button has an accessible name and a 32px target; its icon is hidden from screen readers.
  • With reduced motion the slide and backdrop fade are removed; dragging still follows the finger because it is direct manipulation.

Files

Installed into src/components/shaken, or components/shaken when the project has no src directory.

  • src/components/shaken/ui/sheet.tsxsheet
  • Also installs button@0.2.1registry dependency
  • npm packages: @base-ui/react@^1.9.0React and Tailwind CSS v4 required

Source

The exact source the CLI installs, from /r/items/react/sheet/0.1.0.json.

ui/sheet.tsxShow
ui/sheet.tsx
"use client";

import { Drawer as BaseDrawer } from "@base-ui/react/drawer";
import { type ComponentProps, createContext, useContext } from "react";

type ClassName<State> = string | ((state: State) => string | undefined) | undefined;

function cx(...classes: (string | false | null | undefined)[]) {
  return classes.filter(Boolean).join(" ");
}

/** Prepends base classes while keeping Base UI's state-function form of className working. */
function withBase<State>(base: string, className: ClassName<State>) {
  return typeof className === "function" ? (state: State) => cx(base, className(state)) : cx(base, className);
}

export type SheetSide = "top" | "right" | "bottom" | "left";

const SideContext = createContext<SheetSide>("right");

const swipeDirections = { top: "up", right: "right", bottom: "down", left: "left" } as const;

export interface SheetProps extends Omit<BaseDrawer.Root.Props, "swipeDirection" | "snapPoints" | "snapPoint" | "defaultSnapPoint" | "onSnapPointChange"> {
  /** The screen edge the panel slides in from. A swipe or drag back toward that edge dismisses it. */
  side?: SheetSide;
}

/**
 * Groups the sheet parts and holds its open state. Pass `open`/`onOpenChange` to control it.
 * Built on Base UI Drawer, so it traps focus like a dialog and can be swiped away on touch.
 */
export function Sheet({ side = "right", ...props }: SheetProps) {
  return (
    <SideContext.Provider value={side}>
      <BaseDrawer.Root swipeDirection={swipeDirections[side]} {...props} />
    </SideContext.Provider>
  );
}

/** A button that opens the sheet. Unstyled; pass `className`, or `render={<Button />}` to reuse your button. */
export const SheetTrigger = BaseDrawer.Trigger;

/** A button that closes the sheet. Unstyled; pass `className` or `render`. */
export const SheetClose = BaseDrawer.Close;

const sizes = {
  sm: "[--sheet-size:20rem]",
  md: "[--sheet-size:24rem]",
  lg: "[--sheet-size:32rem]",
} as const;

export type SheetSize = keyof typeof sizes;

// Where the viewport parks the panel, the hairline on its inner edge, and the off-screen position it
// enters from and leaves to. Swipe movement is added to the resting translate while dragging.
const placement = {
  right: {
    viewport: "justify-end",
    popup: cx(
      "h-full w-[min(var(--sheet-size),calc(100vw-3rem))] border-l",
      "translate-x-[var(--drawer-swipe-movement-x,0px)] data-[starting-style]:translate-x-full data-[ending-style]:translate-x-full",
    ),
  },
  left: {
    viewport: "justify-start",
    popup: cx(
      "h-full w-[min(var(--sheet-size),calc(100vw-3rem))] border-r",
      "translate-x-[var(--drawer-swipe-movement-x,0px)] data-[starting-style]:-translate-x-full data-[ending-style]:-translate-x-full",
    ),
  },
  top: {
    viewport: "flex-col justify-start",
    popup: cx(
      "max-h-[calc(100dvh-3rem)] w-full border-b",
      "translate-y-[var(--drawer-swipe-movement-y,0px)] data-[starting-style]:-translate-y-full data-[ending-style]:-translate-y-full",
    ),
  },
  bottom: {
    viewport: "flex-col justify-end",
    popup: cx(
      "max-h-[calc(100dvh-3rem)] w-full border-t pb-[env(safe-area-inset-bottom,0px)]",
      "translate-y-[var(--drawer-swipe-movement-y,0px)] data-[starting-style]:translate-y-full data-[ending-style]:translate-y-full",
    ),
  },
} as const;

export interface SheetContentProps extends BaseDrawer.Popup.Props {
  /** Width of a left or right sheet: 20rem, 24rem, or 32rem, never wider than the screen minus 3rem. */
  size?: SheetSize;
  /** Renders an icon button in the corner that closes the sheet. */
  showCloseButton?: boolean;
  /** Accessible name of the corner close button. */
  closeLabel?: string;
  /** Classes for the backdrop behind the panel. */
  backdropClassName?: string;
  /** Element to portal into. Defaults to `document.body`. */
  container?: BaseDrawer.Portal.Props["container"];
}

/**
 * The sliding panel, rendered in a portal above a backdrop. Lay it out with SheetHeader, SheetBody,
 * and SheetFooter: the header and footer stay put while the body scrolls.
 */
export function SheetContent({
  size = "md",
  showCloseButton = true,
  closeLabel = "Close",
  backdropClassName,
  container,
  className,
  children,
  ...props
}: SheetContentProps) {
  const side = useContext(SideContext);

  return (
    <BaseDrawer.Portal container={container}>
      <BaseDrawer.Backdrop
        className={cx(
          "fixed inset-0 z-50 bg-black/40 dark:bg-black/70",
          // Fades with the swipe so the page shows through as the panel is dragged away.
          "opacity-[calc(1-var(--drawer-swipe-progress,0))]",
          "transition-opacity duration-300 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none",
          "data-[starting-style]:opacity-0 data-[ending-style]:opacity-0 data-[ending-style]:duration-[calc(var(--drawer-swipe-strength,1)*200ms)] data-[swiping]:duration-0",
          backdropClassName,
        )}
      />
      <BaseDrawer.Viewport className={cx("fixed inset-0 z-50 flex", placement[side].viewport)}>
        <BaseDrawer.Popup
          data-side={side}
          className={withBase(
            cx(
              "relative flex flex-col overflow-hidden overscroll-contain outline-none",
              "border-zinc-950/10 bg-white text-zinc-950 shadow-[0_0_48px_-12px_rgb(0_0_0/0.24)]",
              "dark:border-white/15 dark:bg-black dark:text-white dark:shadow-[0_0_64px_-8px_rgb(0_0_0/1)]",
              "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-sky-500",
              // Enter: 300ms quint ease-out from the edge. Exit: 200ms, shorter still after a fast swipe.
              "transition-[translate] duration-300 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none",
              "data-[ending-style]:duration-[calc(var(--drawer-swipe-strength,1)*200ms)] data-[ending-style]:ease-[cubic-bezier(0.32,0.72,0,1)]",
              "data-[swiping]:duration-0 data-[swiping]:select-none",
              placement[side].popup,
              sizes[size],
            ),
            className,
          )}
          {...props}
        >
          {children}
          {showCloseButton ? (
            <BaseDrawer.Close
              aria-label={closeLabel}
              className={cx(
                "absolute top-4 right-4 inline-flex size-8 items-center justify-center rounded-lg text-zinc-500",
                "transition-[background-color,color,scale] duration-150 ease-out active:duration-100 motion-reduce:transition-none",
                "hover:bg-zinc-950/[0.05] hover:text-zinc-950 motion-safe:active:scale-[0.94]",
                "dark:hover:bg-white/[0.08] dark:hover:text-white",
                "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500",
              )}
            >
              <svg aria-hidden="true" viewBox="0 0 16 16" fill="none" className="size-4">
                <path d="M4.5 4.5l7 7M11.5 4.5l-7 7" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
              </svg>
            </BaseDrawer.Close>
          ) : null}
        </BaseDrawer.Popup>
      </BaseDrawer.Viewport>
    </BaseDrawer.Portal>
  );
}

// Top and bottom sheets span the window; keep their content in a readable 48rem column.
const wideGutter =
  "in-data-[side=top]:px-[max(1.5rem,calc((100%-48rem)/2))] in-data-[side=bottom]:px-[max(1.5rem,calc((100%-48rem)/2))]";

/** Wraps the title and description at the top of the panel. Leaves room for the close button. */
export function SheetHeader({ className, ...props }: ComponentProps<"div">) {
  return <div className={cx("grid shrink-0 gap-1.5 px-6 pt-6 pb-4 pr-14", wideGutter, className)} {...props} />;
}

/**
 * The scrolling middle of the panel. Text in it can be selected with a mouse without starting a
 * swipe. Mark a horizontal scroller inside it with `data-base-ui-swipe-ignore` to keep its drags.
 */
export function SheetBody({ className, ...props }: BaseDrawer.Content.Props) {
  return (
    <BaseDrawer.Content
      className={withBase(cx("min-h-0 flex-1 overflow-y-auto overscroll-contain px-6 pb-6 text-sm", wideGutter), className)}
      {...props}
    />
  );
}

/** Holds the actions in a band under a divider at the bottom of the panel. */
export function SheetFooter({ className, ...props }: ComponentProps<"div">) {
  return (
    <div
      className={cx(
        "mt-auto flex shrink-0 flex-col-reverse gap-2 border-t border-zinc-950/[0.07] bg-zinc-950/[0.015] px-6 py-4 sm:flex-row sm:justify-end",
        "dark:border-white/[0.08] dark:bg-transparent",
        wideGutter,
        className,
      )}
      {...props}
    />
  );
}

/** The sheet's heading. Labels the panel with aria-labelledby. */
export function SheetTitle({ className, ...props }: BaseDrawer.Title.Props) {
  return <BaseDrawer.Title className={withBase("text-base leading-6 font-semibold tracking-[-0.01em]", className)} {...props} />;
}

/** Supporting text. Describes the panel with aria-describedby. */
export function SheetDescription({ className, ...props }: BaseDrawer.Description.Props) {
  return (
    <BaseDrawer.Description className={withBase("text-sm leading-relaxed text-zinc-600 dark:text-zinc-400", className)} {...props} />
  );
}