--- url: /reference/items/Sheet/js-api.md --- # JS API The `Sheet` component uses the [`withInView`](https://js-toolkit-v4.studiometa.dev/api/services/mixins.html) and [`withRaf`](https://js-toolkit-v4.studiometa.dev/api/services/mixins.html) mixins of the [`@studiometa/js-toolkit` package](https://js-toolkit-v4.studiometa.dev) and implements the [`Transitionable`](/reference/items/Transition/) contract that [`Dialog`](/reference/items/Dialog/) calls. ## Options ### `position` * Type: `'bottom'` * Default: `'bottom'` The viewport edge the sheet is attached to. Only `bottom` is implemented. Any other value logs a [`sheet.unsupported-position`](#diagnostics) warning, and the sheet behaves as a `bottom` sheet. The option keeps the markup of a bottom sheet stable when the other positions are added. ```html {3}
...
``` ## Refs ### `panel` * Type: `HTMLElement` The sheet itself, inside the stage. It declares the `--sheet` view timeline, and the `IntersectionObserver` that detects a swipe out watches it. ## Properties ### `panel` * Type: `HTMLElement` A getter returning the [`panel` ref](#panel). ### `progress` * Type: `number` How far the panel has entered the visible half of the scroller, from `0` (out of view) to `1` (fully in view). It is what the `entry` range of the `--sheet` timeline measures, and what [`--sheet-progress`](#sheet-progress) publishes. It is measured from layout, so a transform on the panel does not change it. ### `state` * Type: `'entering' | 'leaving' | null` The direction of the last `enter()` or `leave()` call, `null` before the first one. ## Methods ### `enter` * Returns `Promise` Scroll to the end of the scroll range, which puts the panel fully on screen. Resolves on `scrollend`, at once when the scroll lands at once, and after one second when no `scrollend` arrives. Scrolls instantly under `prefers-reduced-motion: reduce`. `Dialog` calls it on open. ### `leave` * Returns `Promise` Scroll back to `0`, which puts the panel off screen. Resolves as soon as the panel is off screen, after a jump to `0`, or on `scrollend` when the user stops the scroll first. Resolves at once when the panel is already out of view, after it jumps to `0` if a swipe is still settling. Scrolls instantly under `prefers-reduced-motion: reduce`. `Dialog` calls it on close. ### `toggle` * Returns `Promise` Call `leave()` if the last call was `enter()`, `enter()` otherwise. ## Timeline and custom properties ### `--sheet` A [view timeline](https://developer.mozilla.org/en-US/docs/Web/CSS/view-timeline) declared on the `panel`, with `view-timeline-inset: 0 100dvh` so that it tracks the visible half of the scroller. `timeline-scope: --sheet` on the root element makes it available to every element of the sheet. Animate with `animation-timeline: --sheet` and `animation-range: entry`. ### `--sheet-progress` Set on the root element **only** where `animation-timeline: view()` is not supported. It equals [`progress`](#progress), from `0` to `1`, and follows every scroll. ## Diagnostics Every one is a development-only warning on the [toolkit diagnostic channel](https://js-toolkit-v4.studiometa.dev/). | Code | Meaning | | ---------------------------- | ------------------------------------------------------------- | | `sheet.unsupported-position` | The `position` option has a value this version does not know. | ## Events The `Sheet` emits no events of its own. Listen to the extendable `open` and `close` events of its parent [`Dialog`](/reference/items/Dialog/js-api#events).