Phila BottomSheet Component

A draggable, snap-point bottom sheet for mobile layouts — the primary use case is overlaying a map (see the OEM Flood Monitor pattern in Storybook), but it works with any scrollable content.

Installation

pnpm add @phila/phila-ui-bottom-sheet @phila/phila-ui-core
# or
npm install @phila/phila-ui-bottom-sheet @phila/phila-ui-core

Import core styles in your main entry file (e.g., main.js|ts):

import "@phila/phila-ui-core/styles/template-light.css";

Usage

<script setup lang="ts">
import { ref } from "vue";
import { BottomSheet } from "@phila/phila-ui-bottom-sheet";

const isOpen = ref(true);
</script>

<template>
  <BottomSheet v-model="isOpen" :snap-points="[20, 50, 75, 100]" scrim>
    <template #header>
      <p>Sheet title</p>
    </template>

    <div>Scrollable content goes here.</div>

    <template #footer>
      <button>Save</button>
    </template>
  </BottomSheet>
</template>

The sheet must render inside a position: relative ancestor with a fixed height — it positions itself with position: absolute; inset: 0. See the OverMap story for the reference layout (sheet stacked over a full-height map container).

Snap points

snapPoints is an array of viewport-height percentages, e.g. [20, 50, 75, 100]. Dragging the grabber moves the sheet between them. A single-value array (the default, [50]) renders a fixed height with no drag handle interaction.

Props

| Prop | Type | Default | Description | | ------------------ | --------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | | snapPoints | number[] | [50] | Snap points as viewport height percentages. Single-value = fixed height, no dragging. | | initialSnapIndex | number | 0 | Which snap index to start at. | | scrim | boolean | false | Show a scrim overlay behind the sheet. | | modelValue | boolean | true | Whether the sheet is open (v-model). | | collapseLabel | string | undefined | Label for the collapse button shown at the largest snap point. | | collapseIcon | IconComponent | undefined | Icon for the collapse button, from @phila/phila-ui-core/icons. | | showHandle | boolean | true | Show the drag handle. When false, the bar is hidden and dragging is disabled, but the spacer area is preserved; snapTo still works. | | className | string | undefined | Additional CSS classes. |

Slots

| Slot | Description | | --------- | -------------------------------------------------------- | | default | Main scrollable content. | | header | Fixed header above the content, with a divider below it. | | footer | Fixed footer below the content, with a divider above it. |

Exposed methods

Access these via a template ref on BottomSheet:

| Method/Property | Type | Description | | ---------------- | ------------------------- | ------------------------------------------------------ | | snapTo | (index: number) => void | Programmatically move to a snap index. | | displayPercent | Readonly<Ref<number>> | The current rendered height, as a viewport percentage. | | isDragging | Readonly<Ref<boolean>> | Whether the sheet is currently being dragged. |

Development

Install Dependencies

pnpm install

Run Demo

pnpm dev

Run lint

pnpm lint

Create Production Build

pnpm build

Publishing to NPM

Follow the release instructions using changesets.

License

MIT