BottomSheet

A sheet that rises from the bottom edge, rests at one or more heights (detents), and follows the finger when dragged.

When to use

• Secondary tasks on mobile or narrow layouts where a peek is useful before committing to the full view: backup lists, share options, filters.
• Content people may want to glance at, then pull up to read in full.
• Not for interruptions that need a decision: use Dialog. On wide layouts prefer a side Drawer.

Usage

import { BottomSheet } from "@/components/iris/bottom-sheet/bottom-sheet";

h(
  BottomSheet,
  {
    trigger: h(Button, { variant: "secondary" }, "View backups"),
    title: "Backups for notdocs",
    description: "6 restore points.",
    detents: [0.45, 0.92],
  },
  backupList,
  h(BottomSheetClose, { asChild: true }, h(Button, null, "Done")),
);

Props

Prop	Type	Default	Description
title	string	—	Required. Sheet heading (dialog title).
description	string	—	Supporting line under the title.
children	ReactNode	—	Required. Sheet body; scrolls inside the sheet at the tallest detent.
trigger	ReactNode	—	The control that opens the sheet; focus returns to it on close.
open / defaultOpen / onOpenChange	boolean / boolean / (open) => void	— / false / —	Controlled or uncontrolled open state.
detents	number[]	[0.45, 0.92]	Resting heights as fractions of the viewport height.
initialDetent	number	0	Index into the sorted detents to open at.
onDetentChange	(index: number) => void	—	Called when the sheet settles at a new detent.
closeLabel	string	"Close"	Accessible label of the close button.
className	string	—	Extra class on the sheet.

BottomSheetClose is the Radix Dialog Close for actions inside the sheet.

Notes

• Built on Radix Dialog: modal focus trap, Escape to close, and title/description wiring. Detent changes are announced ("Sheet expanded", "Sheet collapsed").
• Releases project their velocity to pick the nearest detent; a fast flick always moves at least one detent; pulling past the top rubber-bands. The backdrop dims in proportion to the sheet's height.
• Collapsing scrolls the body back to the top so the peek always shows the start.
• Reduced motion jumps between detents instead of springing.
• Detents are relative to the viewport, so inside an embedded preview the sheet sizes to that frame.