Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
132 KB
Raw Blame

schema_version: 3 template_version: 3 kind: component id: component:BottomSheet authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-24 owners: [cixzhang] review_triggers: [theming, layout, public-api, behavior, accessibility] verified_by: [ packages/core/src/BottomSheet/BottomSheet.test.tsx, packages/core/src/BottomSheet/BottomSheetPanel.test.tsx, packages/core/src/BottomSheet/BottomSheetKeyboard.test.tsx, packages/core/src/BottomSheet/BottomSheetStacking.test.tsx, packages/core/src/BottomSheet/BottomSheetReplace.test.tsx, packages/core/src/BottomSheet/tests/BottomSheetAutofocus.a11y.browser.spec.ts, packages/core/src/BottomSheet/useSheetGestures.test.ts, packages/core/src/Toast/ToastViewport.modalHost.test.tsx, packages/core/src/BottomSheet/tests/BottomSheetNativeModal.a11y.browser.spec.ts, packages/core/src/BottomSheet/tests/BottomSheetKeyboard.a11y.browser.spec.ts, packages/core/src/BottomSheet/tests/BottomSheetDrag.a11y.chromium.spec.ts, packages/core/src/BottomSheet/tests/BottomSheetDetent.interaction.browser.spec.ts, apps/storybook/stories/BottomSheet.stories.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [family:overlay-dismissal] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:container-padding, architecture:layer-runtime, ] contributing: [] system_specs: [ spec:AST-025, spec:AST-099, spec:AST-027/FR8, spec:AST-017/FR7, spec:AST-017/FR25, spec:AST-020,

]

BottomSheet component contract

Intent

BottomSheet presents caller-provided content in a panel that rises from the bottom edge. This record covers consumer anatomy, the native dialog every sheet renders, keyboard-reachable scrolling, theming reachability, the Content area's container padding, and how standalone sheets relate to one another: modal sheets form one stack per document ordered by when they opened, a sheet that closes in the same update another opens is replaced by it with one handoff motion, and non-modal sheets are hosted in the browser's top layer (DEC-2). Multi-step flows are written as one standalone sheet per step driven by one state value; BottomSheetSwitcher is the deprecated predecessor of that pattern (component:BottomSheetSwitcher DEP-0015). Where the shipped sheet does not yet meet a requirement, the row carries a present-tense implementation gap note.

Compatibility and migration

  • Released default preserved: yes, except the block-start inset; with no padding prop and no theme padding, the Content area insets by --spacing-4 on the other logical edges, and padding={0} keeps them unpadded. The block-start inset is never less than the grab bar's height (--spacing-6), so a default sheet's content starts 8px lower, and a padding={0} sheet's content and a lone Section start below the bar
  • Touch release (FR19): a touch release follows UIKit's sheet. A slow or medium touch throw travels less than it did, and a slow touch drag closes the sheet only past halfway from the lowest detent to closed, where it closed past 40 %. A mouse or pen drag is unchanged.
  • Compatibility class: no public prop, type, default, or export changes. Stacking, the replace handoff, and non-modal top-layer hosting are behavior of the existing component, tagged [feat] (spec:AST-017/FR7: a compatible capability) and admissible in a patch under spec:AST-017/FR25 as additive — no released contract described two presented sheets, so the stack gives behavior to a state no contract covered — and as implementation-equivalent for a sheet on its own: a modal sheet presented on its own behaves as released, except that it focuses an eligible data-autofocus descendant on open in every engine (AR4), a [fix] under component:TextInput FR2 and component:Dialog FR2; and a non-modal sheet on its own keeps its documented contract (no scrim, no scroll lock, page interactive, dismissal by purpose, finalFocusRef focused after every close, the element focused when it was shown focused again when it closes while focus is inside it, and focus on open on an eligible data-autofocus descendant, else where that engine's show() focusing steps put it — the panel in Chromium, the first control in Firefox) while its host changes from show() with a page-level z-index to the top layer with none (FR11). One exception, visual only: under prefers-reduced-motion: reduce a lone sheet's entrance and exit follow FR15 (no transform travel; a cross-fade on a coarse pointer or after a touch drag's release, an immediate change otherwise) where the released motion ran its transforms shortened — a motion change under a preference, no change to any state, event, or focus outcome. Two modal sheets open at once stack (FR5) instead of presenting as unrelated dialogs that each dim the page
  • Controlled/uncontrolled behavior: unchanged; isOpen stays fully controlled, and a sheet never writes another sheet's state (FR8)
  • Migration decision: none for callers of BottomSheet. Flows written with BottomSheetSwitcher migrate to standalone steps under component:BottomSheetSwitcher DEP-0015

Consumer migration instructions belong in consumer docs and release notes.

Ownership boundary

Owns

  • The visual Sheet panel and its current bottom-sheet target.
  • The scrolling Content area, its shared viewport/content-box integration, and automatic keyboard-path selection.
  • The Content area's container padding, published per architecture:container-padding.
  • Standalone sheet presentation, including its optional native-dialog Scrim.
  • The native dialog every sheet renders, standalone or switcher-managed (component:BottomSheetSwitcher DEC-1).
  • The stack of presented modal sheets in one document: their order, which one is on top, how far a covered sheet recedes, which backdrop paints the one scrim, and the native top-layer order that realizes it (FR5–FR7, DEC-2).
  • The replace handoff between a sheet closing and a sheet opening in the same update (FR9–FR10).
  • The top-layer hosting of a non-modal sheet (FR11).

Does not own / non-goals

  • Caller-provided content rendered inside the Content area.
  • A separate target for Content area, Handle, or Scrim; none exists on current main.
  • The presentation lifecycle of its dialog and the flow's scrim ownership when the sheet participates in a BottomSheetSwitcher — owned by BottomSheetSwitcher (component:BottomSheetSwitcher DEC-1). The flow as a whole is one level of the stack (FR12).
  • Shared layer hosting or dismissal policy. The Escape and platform-close order is family:overlay-dismissal's; the stack only tells it which sheet can take a close request (FR7).
  • Which Dialog, Drawer, Popover, or other layer paints above a sheet; those keep their own hosting (architecture:layer-runtime). A Dialog opened from a sheet is not a stack level.

Public concepts

No new public concept is introduced. Stacking and the replace handoff are behavior of the existing isOpen / onOpenChange contract: a sheet opened while another modal sheet is open stacks on it; a sheet that closes in the same update as one other sheet opens, from a control inside it, is replaced by it. There is no stack component, context, or opt-in prop. Consumer props and usage remain documented in BottomSheet.doc.mjs.

Behavioral and layout contract

ID Invariant Basis
FR1 The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation. Current source, docs, and tests
FR2 The Sheet panel carries bottom-sheet; Content area, Handle, and Scrim carry no BottomSheet public target. Current source, docs, and tests
FR3 Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from useScrollableArea; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. spec:AST-025; tests
FR4 The Content area pads caller content by the sheet's container inset and publishes the applied inset to descendants as a container publisher, except at the block start: there it applies max(inset, --spacing-6), so resting content starts below the grab bar, and publishes only the inset past that band (max(inset - --spacing-6, 0)). architecture:container-padding
FR5 Modal sheets presented in one document form one stack ordered by open order: the sheet opened most recently is on top; sheets opening in one update are ordered by tree order (a sheet before the sheets rendered in its content, siblings in source order), and the first painted frame already shows that order. Only sheets of one document stack. DEC-2
FR6 A covered modal sheet stays mounted with its state, recedes behind the top sheet, and is blocked: the browser's modal rules block it, and when it contains no presented sheet it is also inert and aria-hidden. Exactly one backdrop is visible for a stack — the bottom open sheet's — and a change of scrim owner lands with no transition, so the page dim is constant through a push, a pop, and a handoff. DEC-2
FR7 Escape, a scrim tap, a swipe, and a platform close request reach only the top sheet of a stack, through that sheet's own onOpenChange and purpose; a covered sheet, and a replaced sheet during its handoff, report themselves absent to the shared family:overlay-dismissal stack while that lasts, so the order among sheets is the sheet stack's and the shared stack stays one registry. DEC-2; family:overlay-dismissal/FR2, /FR3
FR8 A sheet rendered in another sheet's content is presented only while its host is open: it leaves the top layer with its host and is presented again, on top, if its own isOpen is still true when the host reopens. Its isOpen is never written by the host. DEC-2
FR9 Closing the top sheet returns focus into the sheet it reveals: to the element that opened the closing sheet when that element is inside the revealed sheet, else to the revealed sheet's panel; an explicit finalFocusRef outside the revealed sheet yields to its panel in the same way. The last sheet of a stack keeps the standalone rule: finalFocusRef, else the opener. Closing every sheet of a stack in one update returns focus once, to the bottom sheet's finalFocusRef or opener, after the last dialog has closed. A close driven by the stack itself never moves focus. A standalone sheet (not a switcher step) that closes with focus inside it is neither inert nor aria-hidden while that focus stays, and takes no pointer or keyboard activation; when the exit ends, its dialog closes and focus returns in the same task, so focus never sits in a hidden subtree (spec:AST-020 FR1; WCAG 2.2 SC 2.4.3 and 4.1.2). It becomes inert and aria-hidden as soon as focus leaves it. A sheet that closes with focus elsewhere is inert and aria-hidden from the close. DEC-2
FR10 When exactly one standalone sheet closes and exactly one opens in the same update, both of one document and one modality, the closing sheet was the top sheet of its group — its document's modal stack, or, for non-modal sheets, the one open non-modal sheet (FR11) — with the opening sheet set aside, neither dialog contains the other, and the actor — the control last pressed, or, with no fresh press, the element focused when the update began — is inside the closing sheet's dialog or is none (no fresh press, and nothing or only the document body focused, as when code changes the step while focus has fallen to the body), the opening sheet replaces the closing one: it enters above the retained sheet; a retained sheet whose top edge is above the entering sheet's resting top edge moves down to meet it at the same time; the retained sheet fades only after both motions complete; it is inert and aria-hidden from the first frame and takes no dismissal request; the scrim owner is FR6's, the bottom open sheet: when the retained sheet is that owner (a replace at the bottom of the stack) its backdrop keeps the one visible scrim until it leaves and the entering sheet's backdrop takes over with no transition, and when the replace runs above a covered sheet that sheet stays the owner and the retained sheet's backdrop is transparent throughout, so it only fades; focus moves into the entering sheet; and the entering sheet adopts the retained sheet's focus-return target, so closing the flow returns focus to its first opener. A close and an open that fail any condition — different updates, a covered sheet closing, several sheets changing, a sheet closing with its host, or a control outside the closing sheet acting — keep the ordinary push and pop motion and their own focus return. DEC-2
FR11 A non-modal sheet (hasScrim={false}) is presented in the browser's top layer as a manual popover with no backdrop, no scroll lock, and no focus trap, and carries no page-level z-index; where the Popover API is absent it is presented with show() in page stacking order as a reduced fallback. A non-modal sheet shown while a modal dialog that does not contain it is open (a modal sheet, a Dialog) is inert under that modal, so it does not enter the top layer yet — there it would paint above the modal while a press on it lands on the modal — and is presented with show() beneath the modal, with no page-level z-index; a modal on its way out (inert and hidden, or holding focus under FR9) counts as gone. Once no such modal is open the sheet enters the top layer as a manual popover, a top-layer toast viewport re-entering above it (FR14), so page content never paints over an interactive non-modal sheet (spec:AST-027 FR8). A non-modal sheet rendered inside the modal's content is not inert and enters the top layer at once. Non-modal sheets never stack, recede, or own a scrim, and never pair with a modal sheet; because they never stack, the one open non-modal sheet of a document is always the top of its own group, so two non-modal sheets replace each other under FR10 — the closing one being that top — with no backdrop. On a lone open, an eligible data-autofocus descendant — one inside the sheet's own dialog, neither hidden nor inert, that takes focus when asked — takes focus (AR4, the same rule as a modal sheet's); without one, focus goes where the engine's own show() focusing steps would put it when they enter the sheet: in Chromium the panel, whose focusing steps take the first focusable area including a tabindex="-1" container; in Firefox the first focusable control in the content; in WebKit wherever its show() lands. Where the manual-popover host's own focusing steps would land elsewhere than that engine's show() (Chromium's showPopover() lands on the first control), focus arrives where show() would have put it without passing through any control — no control receives a focus or a blur on the way, so a field validating on blur does not fire on open; when the sheet is replacing the sheet the person was in, it takes focus, and a data-autofocus descendant then wins (AR4). On close an explicit finalFocusRef is focused wherever focus is, and otherwise the element focused when the sheet was shown is focused again only while focus is still inside the sheet — the native dialog's own return rule, kept. DEC-2; spec:AST-027/FR8; architecture:layer-runtime
FR12 A modal BottomSheetSwitcher flow is one level of the stack: the dialog of its active step is the flow's level, keeps the flow's rank across the flow's own handoffs, recedes and is blocked when covered, yields its backdrop to the stack's scrim owner, stands down from dismissal while covered, and returns focus by FR9. A standalone sheet rendered in a step's content stacks above the flow and leaves with the step (FR8). A switcher step is never paired under FR10. DEC-2; component:BottomSheetSwitcher/DEC-1
FR13 Every open scrim sheet supplies its dialog as a passive global outlet for app-global surfaces such as toasts (spec:AST-003 FR18: each active native modal, a covered sheet included), and a modal BottomSheetSwitcher flow supplies its active step's dialog — the one its host dialog resolves to, following each handoff; the retained step's dialog, inert and fading, never hosts. Among sheets, the latest outlet — the one a global host renders into — follows the stack's order, not the order the sheets were supplied in: the top sheet is the latest, so a toast lands in the top sheet and never in a covered, inert one, and when the top sheet closes the sheet it reveals is the latest again and takes the host back. A sheet is raised only among sheet outlets: an outlet supplied later by another modal (a Dialog opened from a sheet) stays above every sheet until it closes. A sheet, or a flow, stops supplying as soon as it starts closing, and a native close event that fires while its dialog is open again (the stack re-showing it, or a reopen during its exit) does not take its outlet away. DEC-2; spec:AST-003/FR16, /FR18; architecture:layer-runtime; component:BottomSheetSwitcher/FR10
FR14 When a non-modal sheet enters the top layer, a top-layer toast viewport shown before it leaves and re-enters the top layer in place, keeping focus inside it, so toasts paint above the sheet. DEC-2; architecture:layer-runtime
FR15 Under prefers-reduced-motion: reduce the recede, the return from receded, a push's entrance, a pop's exit and the replace handoff — and a BottomSheetSwitcher step's, which shares the sheet panel's motion — follow design:reduced-motion, keyed on its queries (prefers-reduced-motion: reduce, with pointer: coarse for the cross-fade): no transform motion runs (DR1) — a covered sheet appears in its receded place and size the frame the push lands and returns the same way, the entering sheet appears in its final place, the retained sheet does not align down; on a coarse pointer the entering sheet fades in and the leaving or retained sheet fades out where it is, opacity only, in 200 ms or less (DR2); a dismissal the release of a touch drag started (a swipe past the dismiss line) fades out in place the same way on every pointer (DR2's drag-release clause); on any other pointer every other change is immediate (DR3); the handoff's steps run in the released order, so the retained sheet is hidden and its dialog closed once its fade ends. The constant page dim through a push, a pop and a handoff (FR6) holds as it does with motion. DEC-2; design:reduced-motion
FR16 An open modal sheet is a focus region through Core's shared focus-region module (component:Dialog/DEC-2): in the top sheet, Tab from the last tabbable control moves focus to the first and Shift+Tab from the first moves focus to the last, so focus never leaves the sheet for the browser's own interface. A covered or closing sheet does not answer Tab, and a non-modal sheet contains nothing (FR11). A switcher step (the deprecated BottomSheetSwitcher) is the exception to DEC-2, as component:Dialog DEC-2 states. component:Dialog/DEC-2
FR17 A BottomSheet open on the server, by its own isOpen or as a BottomSheetSwitcher's active sheet, renders closed until hydration (no open styles, no aria-modal, the markup of a closed sheet) and opens in the render after hydration, the first that can enter its native host; it never claims a modality it does not have (spec:AST-020 FR1, WCAG 2.2 SC 4.1.2). The server and hydrating renders produce the same markup (spec:AST-013 FR9), and the open after hydration is settled, with no entry motion; later opens and closes animate as usual (spec:AST-013 FR13). spec:AST-020 FR1
FR18 A finger's pull up past the tallest detent stretches the sheet on spec:AST-094 FR3's rubber band, the same on every pull, with no hold. The sheet's surface reaches below the screen far enough for the whole stretch and the release, so the page under it never shows. A pull on the sheet's body stretches it as a pull on the grabber does, once the content has no room left to scroll that way: content that fits stretches at once, and a long list scrolls to its end first, then holds still while the sheet stretches. At every detent, a list that reaches its end mid-pull holds still while the sheet takes the rest of the pull. A sheet the caller sizes or styles keeps 48 px below the screen, and its stretch stops there. An inline block size, any xstyle and any class name count, because the sheet cannot read their rules. A mouse or a pen keeps its own resisted stretch, at most 48 px (spec:AST-017 FR59). DEC-3; spec:AST-094 FR3
FR19 A release settles on the detent nearest its projected position (spec:AST-094 FR36); a release whose velocity points back toward its start returns to its starting detent (spec:AST-094 FR37). An info sheet whose projection passes the dismiss point closes; a form or required sheet settles on its shortest detent (FR7). Under a finger, the projection is 0.1 s of the release velocity (sheet.release.projectionSeconds, measured from UIKit's sheet), closed counts as one position, and the dismiss point is halfway from the lowest detent to closed. A touch release slower than 250 px/s (sheet.release.minProjectionSpeed, measured) projects nothing, so it settles on the position nearest where it was let go. From 1,008 px/s (sheet.release.fastSpeed, as UIKit's sheet counts a flick), a touch release is a flick: it lands on the first position at or past its projection, at least the next one in its direction. So a flick goes on past the next position once it is faster than 10 px/s for each pixel left to that position, and a flick at the lowest detent closes the sheet. A sheet that a touch release closes leaves on its close spring from the release speed (spec:AST-094 FR38), UIKit's measured swipe dismissal springs.sheetDismissSwipe, a motion role that the theme's tempo scales (spec:AST-094 FR4, FR45). Its scrim fades for as long as that spring takes to settle at the theme's tempo, so the two finish together (spec:AST-094 FR45's spring tiers; spec:AST-108 FR4a). Under reduced motion its exit follows FR15. Implementation gap: the settle on a detent plays --ease-standard over the theme's --duration-medium, at a speed set by the distance left rather than the finger's (spec:AST-094 FR38). Implementation gap: in WebKit, the settle stops advancing while the main thread is blocked (spec:AST-094 FR5). Implementation gap: under a mouse or pen, a release whose velocity points back toward its start still commits when it follows a net downward drag and its projection passes the dismiss point, or when its projection lies nearer the next detent in the drag's direction (spec:AST-094 FR37). Implementation gap: under a mouse or pen, the projection is a scroll view's, a release after 48 px of travel or less projects nothing, and the dismiss point is a dismiss line, so a short fast flick closes an info sheet only when the pointer itself lifts past it (spec:AST-094 FR36, FR43). Implementation gap: a mouse or pen close plays the stylesheet's exit, not the close spring (spec:AST-094 FR43, FR45). spec:AST-094 FR4, FR5, FR36, FR37, FR38, FR43, FR45; spec:AST-108 FR4a; FR7; DEC-4
FR20 A standalone sheet (not a switcher step) removed while open is closed for focus: when it was the standalone or top sheet and focus was inside it, or fell to the body with its removal, focus returns as FR9 (modal) or FR11 (non-modal) state, to finalFocusRef, else the opener while it is still connected; with a sheet open beneath, focus goes into that revealed sheet by FR9. An FR10 replace keeps its handoff to the entering sheet, and a switcher step's change keeps FR12's handoff. Removing a whole stack in one update returns focus once, as FR9 closes it: to the bottom sheet's finalFocusRef or opener. Removing a covered sheet under a top sheet that stays moves no focus, because focus is in the top sheet. A removed opener moves no focus and raises no error. Implementation gap: a BottomSheetSwitcher flow removed while open, alone or as the bottom level of a stack, returns no focus. spec:AST-020/FR1 (WCAG 2.2 SC 2.4.3); FR9; FR11

Allowed variation

  • Caller-provided children may vary without becoming BottomSheet-owned anatomy.
  • Height, snap points, motion phase, and standalone versus switcher hosting may vary without changing the four-part anatomy recorded here.
  • The recede geometry of a covered sheet (its scale and offset per depth), the handoff motion curve, and the order in which the entering and alignment motions of a replace complete may vary under theme motion tokens while FR6 and FR10's ordering and inertness hold.

Representative states

  • A standalone modal sheet renders Sheet panel, Content area, Handle, and Scrim.
  • A standalone non-modal sheet renders Sheet panel, Content area, and Handle without a Scrim.
  • A switcher-managed sheet renders the same panel anatomy in its own dialog while BottomSheetSwitcher coordinates that dialog's lifecycle and the flow's one Scrim (component:BottomSheetSwitcher DEC-1).
  • Stacked: two or more modal sheets presented in one document; the top sheet is interactive, each covered sheet is receded and blocked, one Scrim is visible.
  • Replacing: a retained sheet and an entering sheet both presented through the handoff, the retained one inert — still painting the Scrim when it is the bottom open sheet (FR6), transparent when a covered sheet beneath owns it — then only the entering sheet.
  • Non-modal: a sheet presented as a manual popover in the top layer with no Scrim; the page remains interactive.
  • Reduced motion: the Stacked and Replacing states above with no transform motion — the covered sheet in its receded place at once, the entering and leaving sheets cross-fading on a coarse pointer and changing at once on any other, except a dismissal a touch drag's release started, which fades out in place on every pointer (FR15, design:reduced-motion).

Transformation and precedence order

  • Content area inset: the padding prop, then the theme's padding properties on bottom-sheet, then --spacing-4 on every logical edge. At rest the block-start inset is never less than the grab bar's height (--spacing-6), so the first row starts below the bar; scrolled content still passes under it. That band under the bar is not container padding: the Content area publishes only the block-start padding past it (max(padding - --spacing-6, 0)) and applies the band on top, so a lone Section or a Layout that escapes its padding still starts below the bar. Every other edge applies and publishes the same inset.
  • Stack order: open order, then tree order for sheets opening in one update (FR5). A sheet that closes and reopens takes a new place on top.
  • Native top-layer order is derived from the stack order, not trusted: where the order the dialogs were shown in diverges from the stack order, the stack order holds in the first painted frame (FR5), and no dialog below the first divergence is presented again — a sheet whose place is already right fires no native close.
  • A same-update close and open is tested against FR10 in that order of conditions; the first failing condition makes it a push and a pop.
  • No new height rule is introduced. Its one gesture precedence rule is spec:AST-094 FR14's named exception: at the tallest detent, a pull that carries the content past its end continues as the sheet's stretch (FR18).

Performance and resources

  • Element jobs (architecture:component-style-authoring INV7; the open-layer allowance of spec:AST-017 FR60, DEC-29). An open sheet's frame has these elements, each with one job:
    • the dialog carries the sheet's dialog role, modality and the top layer when the sheet is modal, and hosts the panel at the bottom edge, so a percentage height is a share of the viewport; a covered sheet's recede (FR6) is this element's transform;
    • the panel paints the bottom-sheet target;
    • the grabber bar is the drag handle, and its ::before draws the handle;
    • the body is the scroll area;
    • the content box carries the padding and is the observed content box (FR3);
    • the edge tint gives iOS Safari's toolbar the sheet's color: its own element outside the panel's transform, so it stays flush with the viewport's bottom edge at every detent, rendered only while the sheet is presented;
    • in a BottomSheetSwitcher, each sheet's positioner holds its panel at the block end and hides a sheet that is not presented, so one dialog can switch between sheets.
  • The handle's pill is a pseudo-element and a standalone sheet's dialog holds the panel in place, so a standalone sheet's frame has no positioner or pill element of its own.
  • Elements a presenting component adds beyond this frame are its own to justify.
  • PR1 — One stack per document. Sheets rendered by every copy of the package loaded on a page that shares the stack protocol, and by every React root on it, form one stack per document: their order is their open order, whichever copy or root rendered them. The protocol version is part of the document-global key the copies meet under; a copy on another protocol version keeps a stack of its own, ordering only the sheets it renders, so two copies of different versions on one page are two independent stacks and neither reads the other's state. No public API reaches the ordering.
  • PR2 — No per-level backdrop cost. A stack paints one visible backdrop whatever its depth — the scrim owner's, the bottom open sheet's under FR6 — and every other backdrop in the stack, a covered sheet's or a sheet's above the owner, is transparent, not removed (a switcher flow's dialogs likewise, component:BottomSheetSwitcher FR10).

Accessibility contract

  • AR1 — Keyboard scroll path. The named body is a tab stop while effectively overflowing. On forward Tab entry, the shared hook may delegate to the first sequential native link/button outside navigation-key-owning surfaces. It keeps the body stop for excluded content and skips the body on reverse traversal from the delegated first child.

  • AR2 — Focus continuity. Content, overflow, or eligibility changes MUST NOT move focus. Pointer/programmatic body focus never delegates. A focused body losing overflow remains programmatically focusable.

  • AR3 — Covered and replaced sheets are not exposed. A covered sheet that contains no presented sheet, and a replaced sheet through its handoff, are inert and aria-hidden="true"; the top or entering sheet is the only exposed dialog. A covered sheet that contains the top sheet is left alone, because the top sheet's modality already excludes it (FR6, FR10). Each sheet keeps its own role and accessible name; a non-modal sheet's manual popover host changes neither.

  • AR4 — Focus follows the person through a stack. Opening the top sheet moves focus into it; a replace moves focus into the entering step whatever the native host did; a pop returns focus into the revealed sheet; the last close and a close of the whole stack return focus by FR9, and a sheet removed while open returns focus by FR20. A sheet that opens, on its own or pushed over another sheet, modal or not, focuses its first eligible data-autofocus descendant in every engine: one inside the sheet's own dialog, neither hidden nor inert, that takes focus when asked (component:Dialog FR2's eligibility). Where the engine's native focusing steps landed first (the panel in Chromium, the first control in Firefox) does not count as placed. Without an eligible descendant, focus stays where those steps landed: in Chromium the panel, in Firefox the first focusable control in the content, in WebKit wherever its steps land; a non-modal sheet's manual-popover host lands where that engine's show() would have (FR11). A sheet entering as a replacement (FR10) has its focus placed after the native focusing steps, because they may have left it in the replaced sheet or on the entering panel: there a data-autofocus descendant is focused first, else the panel, so a step flow that opens on a field keeps the keyboard on it.

  • AR5 — What assistive technology perceives of a push, a pop, and a replace. The stack adds no announcement of its own to a push or a pop: it fires no live region, so focus entering the top sheet (push) or returning into the revealed sheet (pop, FR9) is what a screen reader reports, and the covered sheet is hidden meanwhile (AR3). Messages the sheets' own content owes are not the stack's and are delivered by their owners' rules — a message pending in a closing sheet reaches the person through the sheet revealed beneath it (spec:AST-086 FR14). A replace is perceived as focus entering the new step: focus lands on the entering step's data-autofocus field or else its panel (AR4), so the entering dialog's accessible name is announced as focus enters it, and the retained step is hidden from the first frame of the handoff (AR3); the stack announces nothing of the retained step's leaving.

Design relationships

Anatomy or state Design requirement Representation authority Hierarchy role Component contract
Sheet panel Presents the painted bottom-edge surface and owns panel geometry and motion. Current source and public docs Prominent FR1, FR2
Content area Provides the scrolling, inset area for caller-provided sheet content. Current source and tests Prominent FR1, FR2, FR4
Handle Presents the decorative grab affordance and owns the panel's drag interaction region. Current source and tests Supporting FR1, FR2
Scrim Dims and blocks the page in a scrim-backed host; one is visible for a stack. Current source and public docs Supporting FR1, FR2, FR6
Covered sheet Recedes behind the top sheet (a small scale-down and upward offset per depth, the second step shared by every deeper sheet) and is blocked. DEC-2 Supporting FR6
Replaced sheet Holds its place or aligns down to the entering sheet, then fades; keeps the Scrim until it leaves when it is the bottom open sheet (FR6). DEC-2 Supporting FR10

Content area, Handle, and Scrim are stable visible parts, but no current public target reaches them. Their none dispositions record factual reachability, not a decision that they must remain unthemeable.

Theming anatomy

{
  "Sheet panel": {"target": "bottom-sheet"},
  "Content area": {
    "none": {
      "reason": "reachability-gap: No current public target reaches the scrolling content area."
    }
  },
  "Handle": {
    "none": {
      "reason": "reachability-gap: No current public target reaches the handle bar or pill."
    }
  },
  "Scrim": {
    "none": {
      "reason": "reachability-gap: No BottomSheet public target reaches the native dialog backdrop, standalone or switcher-coordinated."
    }
  }
}

Family and system relationships

  • architecture:component-theming-surface owns anatomy qualification, target mapping, and factual none dispositions.
  • architecture:container-padding owns the shared container inset protocol and admits the Content area as a container publisher.
  • architecture:layer-runtime owns the current native-dialog host distinction and records that sheets retain local scrim and swipe behavior.
  • spec:AST-025 owns effective scroll measurement, overflow and containment, automatic keyboard-owner selection, and focus continuity.
  • BottomSheet's on-screen keyboard behavior is owned by spec:AST-099.
  • family:overlay-dismissal owns shared Escape and platform-close ordering. A standalone BottomSheet registers with the shared stack while it is presented and reports itself absent while covered or replaced (FR7); a switcher-hosted sheet is covered by BottomSheetSwitcher's registration.
  • spec:AST-027 FR8 owns top-layer hosting for non-modal surfaces; a standalone non-modal sheet's manual-popover host satisfies it (FR11), and no page-level band remains on that path.
  • architecture:layer-runtime owns the private outlet registry and the toast viewport's hosting; FR13 and FR14 here own only how sheets take part in them (which sheet is the latest outlet, and the toast viewport's re-entry above a non-modal sheet), and that record states the shipped behavior once it ships.
  • spec:AST-017 FR7 gives stacking, the replace handoff, and the non-modal host their [feat] tag and FR25 admits them in a patch (additive and implementation-equivalent); FR26–FR29 govern the switcher's deprecation under component:BottomSheetSwitcher DEP-0015.
  • component:BottomSheetSwitcher DEC-1 owns a flow's own handoff and the presentation of its step dialogs; FR12 here owns only the flow's place as a level of the stack.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1 BottomSheet.test.tsx render, content, Handle, and scrim behavior suites Modal, non-modal, and switcher presentations Removing a documented part fails existing content, structure, or dismissal assertions. audit:BottomSheet/anatomy
FR2 Panel target assertion, source inspection, and theming target inventories Sheet panel, Content area, Handle, and Scrim Removing the panel target or documenting an unshipped child target fails evidence or inventory. audit:BottomSheet/theming
FR3, AR1–AR2 BottomSheetKeyboard.test.tsx; BottomSheetKeyboard.a11y.browser.spec.ts; open Storybook stories fitting/overflow, plain text, usable/unusable/dynamic descendants, focus Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. audit:BottomSheet/accessibility
Layout evidence BottomSheetPanel.test.tsx Floating Handle and scrolling Content area Reordering or merging the stable parts fails existing panel structure and style assertions. audit:BottomSheet/anatomy
FR4 BottomSheetPanel.test.tsx container padding tests; derivedVarRegistry.test.ts default, padding prop, theme padding, lone padded Section child The published inset differs from the applied padding on an edge other than the block start, the block start publishes more than the padding past the grab bar's band, or a lone padded Section escapes into the band. audit:BottomSheet/anatomy
Element jobs Open-sheet element count test against the named job list modal and non-modal sheet, scrim and no scrim An element in the open sheet's frame with no named job, or a named job with no element
Theming anatomy map scripts/check-knowledge.mjs Canonical anatomy and current target inventory Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. audit:BottomSheet/theming
FR5–FR9, FR12–FR15, AR3–AR5 Stacking unit suite (jsdom, native dialog methods stubbed); real-browser per-frame sampling of transforms, backdrop opacity, hit-testing, and focus on the stacking stories in Chromium, WebKit, and real Safari; a real-browser accessibility-tree check (spec:AST-020, spec:AST-009 FR3) that a lone sheet, a stack of two and three, and a replace handoff expose exactly one dialog, the top or entering sheet, with its name, while covered and replaced sheets are hidden, that the stack renders no live region of its own, and that focus enters the entering step's data-autofocus field or panel on a replace; a real-browser run with reduced motion emulated on a fine and on a coarse pointer, sampling per frame that no transform animates, that the covered sheet is in its receded place from the frame the push lands, that on a coarse pointer the entering and leaving sheets change opacity only within 200 ms and on a fine pointer at once, that a swipe dismissal fades out in place on a fine pointer, that the dim is constant and that the handoff still completes; BottomSheetCloseFocus.test.tsx for FR9's close order siblings, separate components, nested in content, inside a switcher step, a switcher flow as a level, out-of-tree-order opens, same-update deep link, depth 1–3, Escape/scrim/swipe/platform close, covered close, close of the whole stack, focus after each pop, two package copies, a second document A covered or replaced sheet is exposed in the accessibility tree, the top sheet is exposed without role dialog or its name, a covered sheet stays interactive, a second backdrop paints, the dim dips or doubles on a handoff, a dismissal reaches a covered sheet, a nested sheet's state is written or it stays open invisibly, or focus lands on body after a pop or a close of the whole stack. audit:BottomSheet/behavior
FR10–FR11 Replace unit suite (jsdom); real-browser parity of the standalone flow against the switcher's handoff — per-frame transforms, opacity, page dim, focus, settled pixels — in Chromium and WebKit, and real Safari for hosting, dim, toast order, and focus; BottomSheetAutofocus.a11y.browser.spec.ts (a lone modal and non-modal sheet opened by a real pointer focus their data-autofocus field); a per-engine focus probe in Chromium, Firefox and WebKit for a sheet with no such field, against that engine's bare show() and showModal() on the same markup push, pop, different updates, covered close, nested, a replace above a covered sheet (the bottom sheet keeps the scrim, the retained sheet only fades), switcher flow, a lone sheet; handoff in both completion orders; reversal mid-handoff in both directions and both tree orders; unrelated owners from a page control; non-modal replace, reversal, show() fallback; a non-modal sheet opened from a modal sheet or a Dialog and rendered outside it (while the modal is open, and once it has closed, with positioned page content), one opened in the update that closes a modal sheet, and one rendered inside the modal's content A replace is recognized for unrelated owners or missed for a real step flow, the retained sheet is exposed or dismissable, the scrim dips, the replaced step stays on screen after a reversal, focus does not enter the step or return to the flow's opener, a non-modal sheet carries a page-level z-index, a toast paints under a non-modal sheet, or an opening sheet, lone or pushed, modal or not, leaves its first eligible data-autofocus field (AR4) unfocused (in Firefox, a control placed ahead of that field may get a focus and a blur first), or one with no such field lands elsewhere than its engine's native host (showModal(), or show()) puts it — in Chromium, its panel, with a ring only after keyboard input; in Firefox, the first focusable control — or a replacement entry fails to focus its data-autofocus field. A non-modal sheet rendered outside an open modal paints above it while a press lands on the modal, or stays beneath page content once that modal has gone. audit:BottomSheet/behavior
FR13–FR14 Toast viewport hosting suite (jsdom, native dialog methods and popover state stubbed); real-browser hit-testing of a toast raised from the top sheet, from a Dialog opened from a sheet after an inner sheet closed, from a sheet re-shown by a reversal, and over a non-modal sheet a lone sheet; a stack of two; sheet → Dialog → sheet → close the inner sheet; a reversal and a reopen during exit, with the stale native close; a non-modal sheet shown after the viewport; a modal switcher flow alone, through a handoff and its close; a flow stacked over a standalone sheet and a standalone sheet over a flow; a non-modal flow A toast renders in a covered or inert sheet, a Dialog opened from a sheet loses the toast to the sheet beneath it, a re-shown sheet loses its outlet to the stale close, a toast raised from a switcher step lands behind the flow or in its retained step, or a toast paints beneath a non-modal sheet. audit:BottomSheet/behavior
FR16 BottomSheet.test.tsx focus-region suite Modal and non-modal sheets; Tab and Shift+Tab at the sheet's edge Tab from the last control leaves a modal sheet, or a non-modal sheet captures Tab audit:BottomSheet/accessibility
FR17 BottomSheet.ssr.test.tsx; BottomSheetSwitcher.test.tsx flow that mounts open Open on the server; hydration; a closed sheet's markup An open server render with aria-modal, open styles, or markup unlike a closed one, a hydration error, no showModal() after hydration, an entry motion on the open right after hydration, or none on a later open fails. audit:BottomSheet/accessibility
FR18 useSheetGestures.test.ts stretch suites; BottomSheetPanel.test.tsx reserve cases; BottomSheetDrag.a11y.chromium.spec.ts Three finger pulls past the top; short content pulled up on its body at five points, the first pull and every one after it; a long list pulled past its end; a mouse pull and a pen pull A capped or held stretch, a pull that stretches less than the one before it, a body pull on short content that moves nothing, a long list that never stretches the sheet once at its end or rubber-bands itself while the sheet stretches, or a reserve under 40% of the viewport on a device with a touch pointer fails, unless the caller sizes or styles the sheet (48 px). audit:BottomSheet/behavior
FR19 BottomSheetDetent.interaction.browser.spec.ts; BottomSheetRelease.a11y.chromium.spec.ts; useSheetGestures.test.ts release suite; resolveSnapPoint.test.ts; BottomSheetDragExit.test.tsx; snapOffsets.test.ts Snap points, real touch: a slow release between detents; 2,000 and 1,200 px/s flicks from tall; the settle, its curve recorded (FR38 gap); in Chromium, the settle through a 700 ms main-thread block (spec:AST-094 FR5) and its rendering trace. Touch: top-detent flicks short of and past the next detent; a flick at the lowest; a slower and a faster release on three stops; a slow drag each side of halfway to closed; a gentle throw; a short slow release; a drag's close, a reopen during it, its scrim at tempo 0.75, 1 and 1.5. Mouse: a quick short drag; a close; one under reduced motion. A close from a control A release that lands off its position (a slow release: the nearest; a touch flick: the first at or past its projection), a flick past the dismiss point that leaves the sheet open, a faster touch release that stops short of a slower one, a touch exit that starts from rest, a scrim that fades longer or shorter than the close spring settles, a mouse drag that flicks or plays the close spring, a reduced-motion mouse close that moves, or a settle that ends off the detent, stalls while the main thread is blocked, or lays out or paints during the settle, fails audit:BottomSheet/behavior
FR20 BottomSheetCloseFocus.test.tsx "BottomSheet removed while open" suite; real-browser focus check in Chromium A modal and a non-modal sheet removed from inside; finalFocusRef; the top sheet of a stack removed; a covered sheet removed under a top sheet that stays; a whole stack removed in one update; a sheet removed in the update that opens another; an opener removed with the sheet Focus on body after a removal from inside, focus on body after a whole stack is removed, focus moved out of the top sheet when a covered sheet is removed, focus pulled out of a sheet that opened in the same update, or an error when the opener is gone, fails. audit:BottomSheet/behavior

Existing tests directly assert the Sheet panel target, Content area placement, Handle structure, and scrim behavior. Source and public target metadata confirm that the other three parts have no public target.

Decision log

DEC-1 — BottomSheet adopts automatic shared keyboard ownership

Reference: component:BottomSheet/DEC-1 Decider: cixzhang, 2026-09-13

BottomSheet supplies its existing label to keyboardAccess.owner="contentOrViewport". The shared hook keeps the overflowing body named and tabbable, delegating forward keyboard entry to a safe first native link/button. Pointer/programmatic focus and excluded content keep the body path. BottomSheet retains stickyContainment="always" because the body deliberately remains the sheet-local Sticky boundary.

A real flow-root content box supplies the hook's observation seam while preserving representative margin, float, percentage-height, flex/grid-child, and hug-height behavior.

DEC-2 — Sheets stack by open order and replace on a same-update switch

Reference: component:BottomSheet/DEC-2 Decider: imdreamrunner, 2026-10-23

Every modal sheet keeps its own open state and its own native dialog. A sheet opened while another modal sheet is open stacks on top of it: the stack is ordered by open order with tree order deciding ties within one update, exactly one backdrop is visible, covered sheets recede and are blocked, dismissal reaches only the top sheet, and the native top layer is put in that order before the first paint when the browser's own order would differ (FR5–FR7). A sheet rendered in another sheet's content is part of it: it leaves and returns with its host and its state stays the caller's (FR8). When the top sheet closes in the same update that one other standalone sheet of the same modality opens, from a control inside the closing sheet, the opening sheet replaces it with the one handoff a step flow needs — entering above, the retained sheet aligning down when taller and fading after both motions, one steady scrim, focus into the entering step, the first opener kept for the flow's close — so a multi-step flow is one standalone sheet per step and one state value (FR10). Non-modal sheets are hosted in the top layer as manual popovers, never stack, and replace each other the same way (FR11). A BottomSheetSwitcher flow is one level (FR12). The ordering is one per document across React roots and across the package copies that share the stack protocol (PR1; a copy on another protocol version keeps its own stack), because the coordinated thing — a document's top layer — is wider than any React tree. Nothing here is public API; a lone modal sheet never notices the stack. Rejected: an ordered list of steps on the switcher (activeSheets), because it changes the switcher's public contract, requires every level of a flow to live under one switcher, and cannot order a sheet opened from elsewhere. Rejected: a <BottomSheetStack> provider or shared dialog that composes levels, because a React context cannot reach a second root, a second copy of the package, or a widget mounted outside it, while module-level singletons already own document-wide facts here (the dismissal stack, the modal outlet registry); the only scoping a provider adds is a "same level" boundary, which FR10's actor condition supplies without a wrapper. Rejected: a stacked or replaces prop to opt a sheet in, because a lone sheet is unaffected and one state value already says what a flow means. Rejected: a page-level z-index on a non-modal sheet to order a replace, because spec:AST-027 forbids a new band; the top layer orders it.

DEC-3 — A pull past the top stretches on every pull

Reference: component:BottomSheet/DEC-3 Decider: the component owner, 2026-11-02

A pull up past the tallest detent stretches the sheet on the rubber band every time, with no cap and no hold, and the page under the sheet never shows: the surface the sheet keeps below the screen is deep enough for the whole stretch and the release (FR18). A pull on the sheet's body counts as a pull on the sheet once its content has no room left to scroll that way. So short content stretches on the first pull and on every pull after it, and a long list scrolls to its end before the sheet stretches. The evidence is an owner screen recording on an iPhone, 2026-11-02, in which most body pulls on short content moved nothing. Rejected: a stretch capped at a 48 px reserve, because it holds still partway through a pull. Rejected: a second mechanism for upward pulls, because the existing pull path already carries them; it only gave too many of them to the content.

DEC-4 — A touch release takes UIKit's sheet values

Reference: component:BottomSheet/DEC-4 Decider: the component owner, 2026-11-02 and 2026-11-03; the spec owners, 2026-11-05

A touch release faster than about 1,000 px/s is a flick, and a flick goes at least to the next position in its direction, as UIKit's sheet measures it: 1,008 px/s, with no more travel than a drag's first 8 px. So a short fast flick at the lowest detent closes the sheet, where the projection alone springs it back (FR19). A sheet a touch drag closes keeps the drag's speed: it leaves on its close spring, starting at the release speed.

On a sheet with snap points, closing it with a flick takes a harder flick than moving it to the next snap point. A flick lands on the first position at or past its projection, 0.1 s of its velocity. So a flick above the lowest detent closes the sheet once its projection passes the lowest detent, and a softer one stops at the next detent. UIKit fits 164 measured releases with any projection from 0.092 to 0.104 s. On an iPhone 17 Pro, with medium 342 pt and gone 812 pt below large, a flick released at large closes from about 3,420 pt/s.

On 2026-11-03 the owner also limited the flick and the close spring to touch, because a short mouse drag that closes a sheet changes how it works on a desktop; a mouse or pen keeps its release. The spec owners then chose UIKit's measured model for every touch release, not for flicks alone, so a faster release never travels less than a slower one. A touch release moving back toward where the drag began still cancels, as spec:AST-094 FR37 requires, where UIKit's sheet settles it by its landing.

Rejected: projecting the release only, because a short fast flick then springs back although the hand meant to close the sheet. Rejected: a fixed multiple of the flick speed for a close from above the lowest detent, because the projection decides it. Rejected: closing from above the lowest detent only when the projection lands nearer closed than any detent, because a flick past the next detent goes on. Rejected: UIKit's projection for flicks alone, because a release just under the flick speed then travels further than one just over it.

Open questions

  • OQ1 — Should Content area, Handle, or Scrim gain a stable public theming target? (human-api) Their current lack of reachability is an audit gap, not settled intent.

Content boundary

This file does not duplicate consumer prop tables, examples, gesture algorithms, implementation steps, or shared layer and theming rules. It links to their owners.