BottomSheet

Local specification source status: preview. Implementation preview pending sign-off.

A mobile bottom-sheet dialog with sheet or full-screen chrome, height presets, swipe-to-dismiss, and optional header and body slots.

import { BottomSheet } from '@cloakedinc/design-system';

Overview

The mobile bottom-sheet dialog — the standard way to present focused, dismissible content over a screen. It renders through a portal, so keep isOpen in parent state and close it from onDismiss.

Use when

size sets the sheet height. Pick it by how much content the sheet carries.

small, large, auto, and full are all in use today; medium is available but currently unused in the app.

Presentation

presentation defaults to sheet — rounded bottom-sheet chrome with an optional drag handle and swipe-to-dismiss. Switch to fullScreen to fill the viewport edge-to-edge with no radius or handle, for immersive flows. A fullScreen sheet reaches the notch, and BottomSheet.Header is what holds its content clear of it — so give one a header even when the chrome is only a title.

Composition

The sheet is composed entirely from slots. BottomSheet.Header is the top chrome, BottomSheet.Title names the sheet from inside it, and BottomSheet.Body holds the content and owns its own scrolling.

<BottomSheet isOpen={isOpen} onDismiss={close} size='large' testId='privacy-detail-sheet'>
    <BottomSheet.Header onClose={close} testId='privacy-detail-sheet-header'>
        <BottomSheet.Title>Privacy detail</BottomSheet.Title>
        <Text variant='body-small' color='secondary'>
            Updated today
        </Text>
    </BottomSheet.Header>
    <BottomSheet.Body>
        <Text variant='body' color='secondary' as='p'>
            Composed slots keep titles, close actions, and body spacing consistent.
        </Text>
    </BottomSheet.Body>
</BottomSheet>

BottomSheet.Title must be a direct child of BottomSheet.Header. A fragment between the two is fine; a wrapper element is not, and @cloakedinc/bottom-sheet-slots fails the lint if you reach for one. The reason is the fullScreen presentation: .header is the single element that carries the sheet's top safe-area inset, and a title that could also sit topmost gives that inset two possible owners — the padding bug this containment closes.

The title shares a row with the close button, and every other header child stacks below that row. It draws no divider of its own; if a rule between header and body is what the design calls for, place a Divider yourself.

variant='serif' swaps the title to the display serif. The default is sans.

Accessible name

The title doubles as the sheet's accessible name, so most sheets need nothing further. A sheet with no title — a picker whose options speak for themselves — takes ariaLabel instead. A slot is invisible to the compiler, so this is the one requirement the types cannot enforce. @cloakedinc/bottom-sheet-slots fails the lint on a sheet with neither, and a sheet whose title only appears at runtime logs a dev-time error — pass ariaLabel there, since a Title that does mount takes the name back.

Required decisions

disableSwipeToDismiss forces a deliberate choice — the sheet closes only via the backdrop or an in-content action, not a swipe.

Usage by variant

Component specification