iOS-style Bottom Sheet Component for Bootstrap 5 – BootstrapSheet

Preview:

Description:

Bootstrap Sheet is a responsive, mobile-friendly bottom sheet component that adds iOS-style, touch-enabled, highly customizable, slide-up panels to your Bootstrap projects.

It’s designed to provide a clean, native-app-like UI for displaying contextual information, forms, or actions on your web apps, without navigating the user away from the current view.

Features:

• Touch-friendly gestures: Physics-based animations provide a smooth, native feel when swiping.
• Backdrop customization: Includes configurable backdrop modes with blur effects and a static option that prevents dismissal when clicking outside the sheet.
• Focus management: Automatically traps keyboard focus within the sheet when open and restores it to the trigger element when closed.
• Accessibility compliance: Implements WCAG 2.1 Level AA standards with proper ARIA attributes, keyboard navigation, and screen reader announcements.
• Event-driven architecture: Exposes lifecycle events that fire during show, hide, and drag interactions for hooking into state changes.

Use cases:

• Mobile navigation menus: Replace traditional dropdown menus with bottom sheets on mobile devices to provide thumb-friendly navigation that matches iOS and Android design patterns.
• Filter and sort panels: Display filtering options for product lists or search results in a way that conserves screen space while remaining easily accessible to users browsing on mobile devices.
• Form wizards and multi-step flows: Break complex forms into digestible steps within a bottom sheet, perfect for checkout processes or account registration where you need to collect information without overwhelming users.
• Action menus and contextual options: Present context-specific actions like share, download, or delete in an iOS-style action sheet that slides up when triggered, keeping primary content visible until the user needs these options.

How to use it:

1. Install and import Bootstrap Sheet via npm or yarn in your project:

# Yarn
$ yarn add bootstrap-sheet
# NPM
$ npm install bootstrap-sheet

import BootstrapSheet from 'bootstrap-sheet';

2. If you’re not using a package manager, download the compiled CSS and JavaScript files and include them in your HTML after Bootstrap’s core files:

<!-- Bootstrap is required -->
<link rel="stylesheet" href="/path/to/cdn/bootstrap.min.css" />
<script src="/path/to/cdn/bootstrap.bundle.min.js"></script>
<!-- Bootstrap Sheet -->
<link href="/dist/css/bootstrap-sheet.min.css" rel="stylesheet">
<script src="/dist/js/bootstrap-sheet.min.js"></script>

3. Create a basic Bottom Sheet with HTML data attributes. Add data-bs-toggle="sheet" to a button and point it to your sheet element with data-bs-target:

The sheet element should have the sheet class and a unique ID. The internal structure follows Bootstrap’s modal component pattern with header, body, and footer sections. The sheet-handle element provides a drag target for swipe gestures.

<!-- Trigger button -->
<button type="button" class="btn btn-primary" data-bs-toggle="sheet" data-bs-target="#mySheet">
  Open Sheet
</button>
<!-- Sheet element -->
<div class="sheet" id="mySheet" tabindex="-1" data-bs-backdrop="true" data-bs-keyboard="true">
  <div class="sheet-handle" data-bs-drag="sheet"></div>
  <div class="sheet-header">
    <h5 class="sheet-title">Bottom Sheet</h5>
    <button type="button" class="btn-close" data-bs-dismiss="sheet" aria-label="Close"></button>
  </div>
  <div class="sheet-body">
    <p>Bottom Sheet Content Here</p>
  </div>
  <div class="sheet-footer">
    <button type="button" class="btn btn-secondary" data-bs-dismiss="sheet">Close</button>
    <button type="button" class="btn btn-primary">Save</button>
  </div>
</div>

4. For more dynamic control, you can initialize and manage the bottom sheet with JavaScript.

const sheet = new BootstrapSheet('#mySheet', {
  // options here
});
// Show the bottom sheet
sheet.show();

5. All configuration options to customize the bottom sheet.

You can pass options via data attributes (e.g., data-bs-backdrop="static") or as a configuration object in JavaScript.

• backdrop: (boolean or 'static', default: true) Includes a backdrop element. Using 'static' creates a backdrop that won’t close the sheet when clicked.
• keyboard: (boolean, default: true) Closes the sheet when the escape key is pressed.
• focus: (boolean, default: true) Puts focus on the sheet when shown and traps focus within it for accessibility.
• gestures: (boolean, default: true) Enables or disables the swipe gestures.
• swipeThreshold: (number, default: 50) The minimum distance in pixels a user must swipe to trigger a close action.
• velocityThreshold: (number, default: 0.5) The minimum swipe velocity in pixels per millisecond required to trigger a close.
• minCloseDistance: (number, default: 50) The minimum distance in pixels for a velocity-based close to occur.
• closeThresholdRatio: (number, default: 0.3) The ratio of the sheet’s height (from 0 to 1) that it must be dragged down to trigger a close upon release.
• animationDuration: (number, default: 300) The duration of the open/close animation in milliseconds.
• projectionTime: (number, default: 200) The time in milliseconds to project the swipe velocity forward for a more natural, momentum-based closing animation.
• dragResistanceUp: (number, default: 0.75) A resistance factor (0-1) when dragging up. A higher value means more resistance.
• dragResistanceDown: (number, default: 0.01) A resistance factor (0-1) when dragging down. A higher value means more resistance.

const sheet = new BootstrapSheet('#mySheet', {
  backdrop: true,
  keyboard: true,
  focus: true,
  gestures: true,
  swipeThreshold: 50,
  velocityThreshold: 0.5,
  minCloseDistance: 50,
  closeThresholdRatio: 0.3,
  animationDuration: 300,
  projectionTime: 200,
  dragResistanceUp: 0.75,
  dragResistanceDown: 0.01
});

6. API methods & properties.

• show(): Opens the sheet.
• hide(): Closes the sheet.
• toggle(): Toggles the sheet’s visibility between shown and hidden.
• dispose(): Destroys the sheet instance and cleans up all associated event listeners.
• getInstance(element): A static method that returns the sheet instance associated with a given DOM element, or null if none exists.
• getOrCreateInstance(element, config?): A static method that retrieves an existing sheet instance for a DOM element or creates a new one if it hasn’t been initialized.
• isShown: (boolean) Returns true if the sheet is currently visible.
• isTransitioning: (boolean) Returns true if the sheet is in the process of animating (opening or closing).

7. Event handlers.

• show.bs.sheet: Fires immediately when the show() method is called.
• shown.bs.sheet: Fires after the sheet has finished its opening transition and is fully visible to the user.
• hide.bs.sheet: Fires immediately when the hide() method is called.
• hidden.bs.sheet: Fires after the sheet has finished its closing transition and is completely hidden.
• slide.bs.sheet: Fires continuously as the user drags or slides the sheet. The event’s detail object contains useful properties like velocity, adjustedY, deltaY, and ratio.

const mySheetEl = document.getElementById('mySheet');
mySheetEl.addEventListener('shown.bs.sheet', (event) => {
  // Logic to run after the sheet is fully visible
  console.log('Sheet is now visible and ready.');
});

8. Bootstrap Sheet exposes Sass variables for theming. Override these in your own Sass files before importing the library:

// Z-index
$sheet-zindex: 1057 !default;
// Dimensions
$sheet-width: 100vw !default;
$sheet-max-width: 100% !default;
$sheet-max-height: 90vh !default;
// Colors
$sheet-bg: var(--bs-body-bg, #fff) !default;
$sheet-backdrop-bg: rgba(0, 0, 0, 0.5) !default;
$sheet-backdrop-backdrop-filter: blur(2px) !default;
// Transitions
$sheet-transition-duration: 0.3s !default;
$sheet-transition-timing: ease-out !default;
// Handle
$sheet-handle-bg: var(--bs-gray-400, #dee2e6) !default;
$sheet-handle-hover-bg: var(--bs-gray-500, #adb5bd) !default;
$sheet-handle-width: 3rem !default;
$sheet-handle-height: 0.25rem !default;
$sheet-handle-margin: 0.5rem auto !default;
$sheet-handle-hit-area: 2rem !default;
// Spacing
$sheet-padding-x: 1rem !default;
$sheet-padding-y: 1rem !default;
$sheet-header-padding-y: 0.75rem !default;
$sheet-body-padding-y: 1rem !default;
$sheet-footer-padding-y: 0.75rem !default;
// Visual effects
$sheet-box-shadow: 0 -2px 10px rgba(0, 0, 0, 0.1) !default;
$sheet-border-width: 1px !default;
$sheet-border-color: var(--bs-border-color, #dee2e6) !default;
$sheet-border-radius: 1rem 1rem 0 0 !default;
// Focus
$sheet-focus-ring-width: 0.25rem !default;
$sheet-focus-ring-color: rgba(13, 110, 253, 0.25) !default;
// Animations
$sheet-shake-distance: 10px !default;
// States
$sheet-disabled-opacity: 0.65 !default;

FAQs:

Q: How do I prevent the sheet from closing when users click the backdrop?
A: Set data-bs-backdrop="static" on the sheet element or pass backdrop: 'static' in the JavaScript options. This displays the backdrop but disables the click-to-dismiss behavior, forcing users to interact with the sheet’s close buttons or press Escape.

Q: Can I customize the drag handle position or remove it entirely?
A: Yes. The drag handle is optional and can be removed by deleting the <div class="sheet-handle" data-bs-drag="sheet"></div> element. Without a handle, users can still dismiss the sheet using buttons or the Escape key. If you want to make the entire header draggable, add data-bs-drag="sheet" to the header element.

Q: Does Bootstrap Sheet work with server-side rendering?
A: Yes, the component initializes after the DOM loads, so it works with server-rendered HTML. Just ensure the Bootstrap Sheet JavaScript loads after the initial render. For frameworks like Next.js, import the library in a useEffect hook or client-side only component.

Q: How do I make the sheet body scrollable when content overflows?
A: The sheet body automatically becomes scrollable when content exceeds the maximum height. You can control this behavior using CSS by setting a max-height on the sheet-body element and ensuring overflow-y is set to auto. Bootstrap Sheet preserves scroll position during drag gestures to prevent accidental scrolling while swiping.

Q: Can I animate multiple sheets or nest them?
A: Multiple sheets can exist on the same page, but only one should be visible at a time due to z-index stacking and accessibility concerns with nested focus traps. If you need sequential sheets, hide the first before showing the second. Nesting sheets creates confusing interaction patterns and should be avoided.

Q: Does the library respect the prefers-reduced-motion setting?
A: Yes, Bootstrap Sheet checks for the prefers-reduced-motion media query and disables animations when users have requested reduced motion in their system settings. The sheet still functions normally but transitions happen instantly rather than animating.

Q: How do I load dynamic content into a sheet after it opens?
A: Listen for the shown.bs.sheet event, which fires after the sheet becomes visible. This is the appropriate time to fetch data or initialize dynamic content that requires the sheet to be in the DOM and visible for measurements or rendering.