pure-web-bottom-sheet

![GitHub license](https://github.com/viliket/pure-web-bottom-sheet/blob/main/LICENSE)
![Build status](https://github.com/viliket/pure-web-bottom-sheet/actions/workflows/test.yml)
![Bundle size](https://bundlejs.com/?q=pure-web-bottom-sheet)
![Bundle size (compressed)>)](https://bundlejs.com/?q=pure-web-bottom-sheet)
![Version](https://www.npmjs.com/package/pure-web-bottom-sheet)

A lightweight, framework-agnostic bottom sheet component leveraging CSS scroll snap
and implemented as a Web Component.
Its key features include:

- Native scroll-driven sheet movement and snap points - uses the browser’s own
scroll mechanics instead of JavaScript-driven animations to adjust the sheet position
through CSS scroll snapping
- Near Zero-JavaScript operation on modern browsers - core functionality is
pure CSS
- Framework-agnostic - works with any framework or vanilla HTML
- Easy customization with a simple API
- Accessibility through native elements (Dialog
or Popover API)
supporting touch, keyboard, or mouse scrolling
- Server-side rendering (SSR) compatible with declarative Shadow DOM support
- Cross-browser support - tested on Chrome, Safari, and Firefox (desktop and
mobile)

The component uses CSS scroll snap and CSS scroll-driven animations
for its core functionality. It uses minimal JavaScript for backward compatibility
and optional features, such as swipe-to-dismiss. Relying on browser-driven scrolling
physics ensures a native-like feel across different browsers and a performant implementation
by not relying on JavaScript-driven animation logic.

For server-side rendering or static site generation, the component includes declarative Shadow DOM
templates to avoid flash of unstyled content (FOUC) when displaying the bottom sheet
initially open on page load.

For technical details behind the implementation, read Native-like bottom sheets on the web: the power of modern CSS.

https://github.com/user-attachments/assets/d25beef6-7256-4b7c-93ca-7605f73045b8

📦 Installation

``sh npm install pure-web-bottom-sheet`

`💻 Usage`

`$3`


  #️⃣ Example code - plain non-dismissible bottom sheet

`html Vanilla HTML example


      

      
      

        Custom header

      

      
        Custom footer

      
      
Custom content


  #️⃣ Example code - modal bottom sheet with dialog integration

`html Vanilla HTML example


        
          
          

          

          
          

            Custom header

          

          
            Custom footer

          
          
Custom content

`$3`


  #️⃣ Example code  - plain non-dismissible bottom sheet

`astro --- import { bottomSheetTemplate } from "pure-web-bottom-sheet/ssr"; ---

{/ Declarative shadow DOM for SSR support (optional) /}

{/ Snap points /}


  

  
  

    Custom header

  

  
    Custom footer

  
  Custom content


  #️⃣ Example code  - modal bottom sheet with dialog integration

`astro --- import { bottomSheetTemplate } from "pure-web-bottom-sheet/ssr"; ---


    
      {/ Declarative shadow DOM for SSR support (optional) /}
      
      
      

      

      
      

        Custom header

      

      
        Custom footer

      
      
Custom content

`$3`

For React, the library provides wrapper components to make it easier to use the component and provide SSR support out of the box.


  #️⃣ Example code - plain non-dismissible bottom sheet

`tsx import { BottomSheet } from "pure-web-bottom-sheet/react";

function Example() { return (


      

        Custom header

      

      
        Custom footer

      
      
Custom content

    
  );
}


  #️⃣ Example code - modal bottom sheet with dialog integration

`tsx import { BottomSheet, BottomSheetDialogManager, } from "pure-web-bottom-sheet/react";

import { useRef } from "react";

function Example() { const dialog = useRef(null);

return (


      
        
        
      

      
        
          
            
            
            
            
              Custom header

            

            
              Custom footer


  );
}

`$3`

Similarly, for Vue, the library provides wrapper components to make it easier to use the component and provide SSR support out of the box.


  #️⃣ Example code - plain non-dismissible bottom sheet

`vue`


  #️⃣ Example code - modal bottom sheet with dialog integration

`vue`

`▶️ Demos`

See live examples and interactive demos

`📄 API reference`

`$3`

The element can be used as a standalone component, optionally with the HTML Popover API (see the _Examples_ section below), or together with a dialog element (seeelement in the following section). When used without a dialog wrapper element or without the HTML Popover API, the bottom sheet is non-dismissable. This approach can be useful, e.g., when using the bottom sheet as an overlay that should always remain visible.

#### Example composition

`html


  

  
  
  

    Custom header

  
  
  

    Custom footer

Custom content`

#### Attributes

- content-heightSpecifies that the sheet's maximum height is based on the height of its contents. By default, when this attribute is not set, the sheet's maximum height is based on the--sheet-max-heightproperty (see below) > ℹ️ Note: Not applicable when using thenested-scrollattribute -nested-scrollSpecifies whether the bottom sheet acts as a scrollable container that allows scrolling its contents independent of the bottom sheet's snap position -nested-scroll-optimizationSpecifies that the bottom sheet uses resize optimization for the nested scroll mode to avoid reflows during sheet resizing. Only relevant whennested-scrollis also true. Not relevant forexpand-to-scrollmode since it already avoids reflows. > ℹ️ Note: This attribute is experimental. -expand-to-scrollSpecifies that the content of the bottom sheet can only be scrolled after the bottom sheet has been expanded to its full height > ℹ️ Note: Only applicable whennested-scrollattribute is also set -swipe-to-dismissSpecifies that the bottom sheet can be swiped down to dismiss, and it will have a snap point on the bottom to snap to close it > ℹ️ Note: Only relevant when either: > > - the is placed inside a

 wrapped
  >   in

bottom-sheet-dialog-manager

 element
  > - using the Popover API (

popover

 attribute on the bottom-sheet).
#### Slots

- Default slot Defines the main content of the bottom sheet. -snap(optional) Defines snap points for positioning the bottom sheet. If not specified, the bottom sheet will have a single snap point--snap: 100%(maximum height). Note that when the has the swipe-to-dismissattribute set, it also has a snap point at the bottom of the viewport to allow swiping down to dismiss it. Each snap point element should: - Be assigned to this slot - Specify the--snapcustom property to set to the wanted offset from the viewport top. For instance,

 creates a
    snap point at 50vh from the bottom of the viewport (vertical center), and
    a snap point with

--snap: 25vh

 would position the sheet at 25vh from the viewport
    bottom. You may use any CSS length units, such as

px, vh

 (based on viewport
    height), or

 (based on sheet max height).
  - Optionally specify the class

initial

 to make the bottom sheet
    initially snap to that point each time it is opened. Note that
    only a single snap point should specify this class.
-

header

 (optional)  
  Optional header content that is displayed at the top of the bottom sheet.
-

footer

 (optional)  
  Optional content that is displayed at the bottom of the bottom sheet.
#### CSS custom properties

- --sheet-max-heightControls the maximum height of the bottom sheet. E.g.,--sheet-max-height: 50dvh;means that the dialog max height is half of the dynamic viewport height, and--sheet-max-height: 100dvh;means that the dialog max height is the full dynamic viewport height ---sheet-backgroundSpecifies thebackgroundproperty of the bottom sheet ---sheet-border-radiusSpecifies the border radius of the bottom sheet

#### Events

- snap-position-change - type: CustomEvent<{ snapPosition: string; }>Notifies that the sheet snap position has changed. Positions:"0"indicates a fully expanded position,"2"indicates a fully collapsed (closed) position, and"1" indicates an intermediate position.

`$3`

The element is used when the bottom sheet should act as a modal that can be opened and closed. This element should have a single nativedialogelement as its child, which itself should have a singlebottom-sheet element as its child. The purpose of the is to provide additional CSS styles to the nativedialogelement, and to handle closing the dialog when clicking on the backdrop, and to implement the swipe-to-dismiss functionality.

Example HTML structure:

`html

`🎨 Customization`

The bottom sheet exposes all its relevant parts to allow adding custom styles or overriding the default styles.

Here are the relevant CSS selectors for the sheet customization:

- bottom-sheet-bottom-sheet::part(sheet)-bottom-sheet::part(handle)-bottom-sheet::part(content)-bottom-sheet::part(header)-bottom-sheet::part(footer)`

🤝 Contributing

Contributions are welcome! Check out the contributing guide to get started.