An open source design system that's fully customizable and agent ready
TypeScript
docs(lab): clarify BottomSheet no-scrim behavior (#4969)
Xinzi Zhou479392fc7052
diff --git a/apps/storybook/stories/BottomSheet.stories.tsx b/apps/storybook/stories/BottomSheet.stories.tsxindex 42073f5261..e83fbe17be 100644--- a/apps/storybook/stories/BottomSheet.stories.tsx+++ b/apps/storybook/stories/BottomSheet.stories.tsx@@ -100,23 +100,20 @@ export const TallSheet: Story = {},};-export const NonModal: Story = {+export const NoScrim: Story = {render: () => {const [isOpen, setIsOpen] = useState(false);const [count, setCount] = useState(0);return (<>- {/* With hasScrim={false} the sheet is non-modal: this background stays- clickable while the sheet is open (no scrim, no scroll lock). Open- the sheet, then tap the counter — it still responds. The story- renders in its own iframe in Docs (see meta docs.story), so the- sheet gets a real mini-viewport and behaves correctly. */}+ {/* A scrim is the semi-transparent layer that covers and blocks the+ background. With hasScrim={false}, this page stays interactive. */}<VStack gap={3}>- <Heading level={3}>Live page (background)</Heading>+ <Heading level={3}>Live page behind the overlay</Heading><Text type="supporting" color="secondary">- A non-modal sheet (hasScrim={'{false}'}) leaves this content- interactive. Open the sheet, then tap the counter below — it keeps- working, and there is no dimming behind the sheet.+ A scrim is the semi-transparent overlay that covers and blocks the+ background. This example has no scrim, so the page stays visible and+ interactive. Open the sheet, then tap the counter below.</Text><Button label="Open sheet" onClick={() => setIsOpen(true)} /><Button@@ -132,10 +129,11 @@ export const NonModal: Story = {height="capped"><Section padding={4}><VStack gap={3}>- <Heading level={3}>Non-modal sheet</Heading>+ <Heading level={3}>No scrim</Heading><Text type="supporting" color="secondary">- No scrim; the page behind stays live. Drag the handle to resize,- flick down to dismiss, or press Escape while focus is here.+ This is still an overlay, not inline content. The page behind+ stays live. Drag the handle to resize, flick down to dismiss, or+ press Escape while focus is here.</Text><Divider />{Array.from({length: 8}, (_, i) => (diff --git a/packages/lab/src/BottomSheet/BottomSheet.doc.mjs b/packages/lab/src/BottomSheet/BottomSheet.doc.mjsindex c8da23ca24..6be4ce716d 100644--- a/packages/lab/src/BottomSheet/BottomSheet.doc.mjs+++ b/packages/lab/src/BottomSheet/BottomSheet.doc.mjs@@ -47,7 +47,7 @@ export const docs = {{name: 'hasScrim',type: 'boolean',- description: "Whether to render a modal scrim behind the sheet. true (default) uses showModal(): top layer, focus trap, ::backdrop scrim, body scroll lock, and tap-scrim-to-dismiss, with the background inert. false uses show(): a non-modal sheet with no scrim, leaving the page behind interactive and scrollable (like Material's standard bottom sheet or an iOS undimmed detent). Escape still closes while focus is inside, and drag/flick-to-dismiss still work.",+ description: "Whether to render a scrim, the semi-transparent overlay that covers and blocks the background, behind the sheet. true (default) uses showModal(): top layer, focus trap, ::backdrop scrim, body scroll lock, and tap-scrim-to-dismiss, with the background inert. false still renders a viewport-anchored overlay above the page, not inline content, but uses show() with no scrim, leaving the page behind interactive and scrollable. Escape still closes while focus is inside, and drag/flick-to-dismiss still work.",default: 'true',},],@@ -57,7 +57,7 @@ export const docs = {{ guidance: true, description: 'Use for mobile-first surfaces (filters, share sheets, quick actions) where the content should rise from the bottom edge.' },{ guidance: true, description: 'Keep the caller as the source of truth: derive isOpen from state and clear it in onOpenChange.' },{ guidance: true, description: "Pick the starting height that fits the content: 'hug' for short bounded content, 'capped' for lists, 'tall' for streaming/resizing content; the user can then drag between snap points." },- { guidance: true, description: "Use hasScrim={false} (non-modal, no scrim) for a peek surface that must coexist with a live page behind it (e.g. a panel over a map); keep the default (hasScrim) for focused tasks where the background should be inert." },+ { guidance: true, description: "Use hasScrim={false} for a floating, no-scrim overlay that must coexist with a live page behind it (e.g. a panel over a map). It remains viewport-anchored rather than rendering inline. Keep the default for focused tasks where the background should be inert." },{ guidance: false, description: 'Use a BottomSheet for desktop inspectors or master-detail; use Drawer (side="end", hasScrim={false}) instead.' },],},@@ -95,7 +95,7 @@ export const docs = {</BottomSheet>`,},{- label: 'Non-modal sheet (no scrim): page stays interactive',+ label: 'No scrim',code: `const [isOpen, setIsOpen] = useState(true);<BottomSheetisOpen={isOpen}@@ -117,7 +117,7 @@ export const docsDense = {{ guidance: true, description: 'Use for mobile-first bottom surfaces (filters, share sheets, quick actions).' },{ guidance: true, description: 'Derive isOpen from state; clear it in onOpenChange.' },{ guidance: true, description: "Pick a height that fits: 'hug' for short content, 'capped' for lists, 'tall' for streaming content." },- { guidance: true, description: "hasScrim={false} for a non-modal peek over a live page; default (hasScrim) for focused tasks (inert background)." },+ { guidance: true, description: "hasScrim={false} for a floating no-scrim overlay over a live page; it is not inline. Keep the default for focused tasks (inert background)." },{ guidance: false, description: 'Use for desktop inspectors or master-detail; use Drawer instead.' },],},diff --git a/packages/lab/src/BottomSheet/BottomSheet.tsx b/packages/lab/src/BottomSheet/BottomSheet.tsxindex af50fb77cf..b711b74194 100644--- a/packages/lab/src/BottomSheet/BottomSheet.tsx+++ b/packages/lab/src/BottomSheet/BottomSheet.tsx@@ -297,9 +297,10 @@ export interface BottomSheetProps extends BaseProps<HTMLDialogElement> {* - `true` (default) — `showModal()`: renders in the top layer with a focus* trap, a `::backdrop` scrim, body scroll lock, and tap-scrim-to-dismiss.* The background is inert. Use for focused tasks (filters, forms).- * - `false` — `show()`: a non-modal sheet with **no scrim**. The page behind+ * - `false`: `show()` renders a viewport-anchored overlay with **no scrim**. It is+ * still layered above the page, not rendered inline, but the page behind* stays interactive and scrollable (like Material's *standard* bottom- * sheet, or an iOS undimmed detent). Escape still closes while focus is+ * sheet or an iOS undimmed detent). Escape still closes while focus is* inside the sheet, and drag/flick-to-dismiss still work. Use for a peek* surface that coexists with the page (e.g. a panel over a live map).* @default true