DOCSEARCHbyAlgolia
Submit Docs

vaul-svelte

repository·main·Indexed 20 days ago

https://github.com/huntabyte/vaul-svelte

An unstyled, mobile-friendly drawer component for Svelte, ported from the React Vaul library. Built using Bits' Dialog primitive, it provides a modular API including Drawer.Root, Trigger, Content, and Overlay. Features include customizable snap points, background scaling, and support for multiple movement directions (top, bottom, left, right).

Tokens
1.8K
Snippets
4
Records
8
Agent score
71%

What's inside vaul-svelte

  2. Basic Usage of Vaul-Svelte

    main

    The drawer is composed of several sub-components. A standard implementation includes a Drawer.Root to manage state, a Drawer.Trigger to open it, and a Drawer.Portal containing the Drawer.Content and Drawer.Overlay to ensure the drawer is rendered correctly in the DOM.

    <script>
	import { Drawer } from "vaul-svelte";
</script>

<Drawer.Root>
	<Drawer.Trigger>Open</Drawer.Trigger>
	<Drawer.Portal>
		<Drawer.Content>
			<p>Content</p>
		</Drawer.Content>
		<Drawer.Overlay />
	</Drawer.Portal>
</Drawer.Root>

  3. Configure Drawer.Root options

    main

    The Drawer.Root component manages the drawer's state and behavior. You can control its visibility by binding to the open prop or using the onOpenChange prop.

    Key configuration options include:

    • shouldScaleBackground: Enables background scaling. This requires a wrapper element in your app with the [data-vaul-drawer-wrapper] data attribute.
    • closeThreshold: A number between 0 and 1 (e.g., 0.5) that determines how much the user must swipe to trigger a close action.
    • scrollLockTimeout: Duration (in ms) after which the drawer becomes non-draggable if the user scrolls content inside the drawer. Defaults to 500.
    • snapPoints: An array of numbers (0-100) representing the percentage of screen height for snap points (e.g., [0.2, 0.5, 0.8]), or absolute pixel values.
    • fadeFromIndex: The index of the snapPoint at which the overlay fade effect begins. Defaults to the last snap point.
    • direction: The movement direction: 'top', 'bottom' (default), 'left', or 'right'.
    • backgroundColor: The background color of the body when shouldScaleBackground is active. Defaults to black.
    • [data-vaul-no-drag]: Adding this data attribute to an element prevents the drawer from being dragged when interacting with that element.

  4. Drawer Sub-components Reference

    main

    Vaul-Svelte provides several specialized components to build the drawer UI. Most of these inherit props from the underlying Bits' Dialog primitive:

    • Drawer.Trigger: The element that triggers the drawer to open.
    • Drawer.Content: The container for the drawer's actual content.
    • Drawer.Overlay: A layer that covers the background when the drawer is open.
    • Drawer.Title: An accessible title for screen readers.
    • Drawer.Description: An optional accessible description for screen readers.
    • Drawer.Close: A button used to close the drawer.
    • Drawer.Portal: A component that portals the drawer content into the document body.

  5. Import the Vaul Drawer components and types

    main

    The vaul-svelte package provides a modular Drawer API. You can access all Drawer components (such as Root, Trigger, Content, etc.) through the Drawer namespace and import the DrawerDirection type for controlling drawer orientation.

    To use the library, import the Drawer namespace from vaul-svelte.

    import { Drawer } from 'vaul-svelte';
import type { DrawerDirection } from 'vaul-svelte';

// Example usage of the Drawer namespace
// <Drawer.Root>
//   <Drawer.Trigger>Open</Drawer.Trigger>
//   <Drawer.Content>
//     Content goes here
//   </Drawer.Content>
// </Drawer.Root>

  6. Use the Vaul Drawer component

    main

    The vaul-svelte package provides a drawer component implementation for Svelte. All primary components and types are exported from the root entrypoint. To use the drawer, you typically compose several subcomponents including Drawer.Root, Drawer.Trigger, Drawer.Content, and Drawer.Overlay.

    <script>
  import { Drawer } from 'vaul-svelte';
</script>

<Drawer.Root>
  <Drawer.Trigger>Open Drawer</Drawer.Trigger>
  <Drawer.Overlay />
  <Drawer.Content>
    <Drawer.Title>Drawer Title</Drawer.Title>
    <Drawer.Description>Drawer Description</Drawer.Description>
    <p>Drawer Content</p>
    <Drawer.Close>Close</Drawer.Close>
  </Drawer.Content>
</Drawer.Root>

  7. Use sub-component props for Vaul

    main

    The Vaul component uses sub-components for its internal structure. These components inherit their prop types from bits-ui's Dialog primitive, ensuring compatibility with standard accessible dialog patterns.

    • OverlayProps: Props for the Overlay component.
    • ContentProps: Props for the Content component.
    • TitleProps: Props for the Title component.
    • DescriptionProps: Props for the Description component.
    • CloseProps: Props for the Close component.

  8. Configure the Vaul Drawer component

    main

    The Vaul component (represented by the Props type) accepts several configuration options to control its behavior, snap points, and appearance. You can use these props to manage the open state, handle drag events, and customize the background scaling effect.

    Key Props

    • State Management:

      • open: A boolean to control the open state. You can bind to this for programmatic control.
      • onOpenChange: A callback function triggered when the open state changes.
      • activeSnapPoint: The current snap point. Bind to this to programmatically change the drawer's position.
      • onActiveSnapPointChange: A callback triggered when the active snap point changes.

    • Interaction & Dismissal:

      • dismissible: If false, the user cannot swipe or click outside to close the drawer; you must provide a manual close mechanism.
      • closeThreshold: A number between 0 and 1 determining how far a user must swipe to close the drawer (e.g., 0.5 closes it at 50% height).
      • onDrag / onRelease: Callbacks for when the drawer is being dragged or released.
      • onClose: A callback triggered when the drawer is about to close.

    • Snap Points & Animation:

      • snapPoints: An array of numbers (0 to 100) representing the percentage of screen height, or absolute px values.
      • fadeFromIndex: The index of the snapPoints array at which the overlay fade effect begins. Defaults to the last snap point.
      • direction: The direction the drawer opens from (e.g., 'bottom'). Defaults to 'bottom'.

    • Visuals:

      • shouldScaleBackground: If true, the background scales down when the drawer is open.
      • backgroundColor: The color of the body background when scaling is enabled. Defaults to 'black'.
      • scrollLockTimeout: Duration in ms to wait before unlocking scroll after interacting with content inside the drawer. Defaults to 500.