Configuration | swipe-bar

Provider Props

Every prop on SwipeBarProvider sets the default for all sidebars. Individual sidebar components can override any of these.

provider-props.tsx

<SwipeBarProvider
  sidebarWidthPx={320}              // width for left/right bars
  sidebarHeightPx={window.innerHeight} // height for bottom sheet
  transitionMs={300}                // open/close animation duration
  edgeActivationWidthPx={40}        // swipe-from-edge detection zone
  dragActivationDeltaPx={20}        // minimum drag distance to activate
  showOverlay={true}                // dim backdrop when open
  overlayBackgroundColor="rgba(0, 0, 0, 0.5)"
  closeSidebarOnOverlayClick={true} // tap overlay to close
  fadeContent={false}               // fade main content when open
  fadeContentTransitionMs={100}     // fade animation duration
  isAbsolute={false}                // overlay vs. push layout
  showToggle={true}                 // show built-in toggle button
  toggleIconColor="white"
  toggleIconSizePx={40}
  toggleIconEdgeDistancePx={40}
  mediaQueryWidth={640}             // swipe gestures below this width
  swipeBarZIndex={30}
  toggleZIndex={15}
  overlayZIndex={20}
  swipeToOpen={true}
  swipeToClose={true}
  disableSwipe={false}              // kills all gesture interaction
  disabled={false}                  // disables everything
>
  {children}
</SwipeBarProvider>

Sidebar Component Props

Each sidebar component accepts the same options as the provider (for overriding) plus a few component-specific props:

sidebar-props.tsx

// All three sidebar components accept these additional props:
<SwipeBarLeft
  id="primary"                 // multi-instance identifier (all directions)
  className="..."              // CSS class for the sidebar container
  ToggleComponent={<MyBtn />}  // replace the default toggle button
  ariaLabel="Navigation"       // accessible label
  defaultOpen={false}          // open on mount
  resetMetaOnClose={false}     // clear meta when sidebar closes
  disabled={false}             // disable this specific sidebar
  showRail={false}             // left/right only: close to icon rail on desktop
  railWidthPx={64}             // rail width when showRail is on

  // Override any provider-level option:
  sidebarWidthPx={400}
  showOverlay={false}
  isAbsolute={true}
  fadeContent={true}
>
  <nav>Single child required</nav>
</SwipeBarLeft>

// Bottom sheet has additional props:
<SwipeBarBottom
  id="primary"                 // multi-instance identifier
  sidebarHeightPx={500}        // sheet height
  midAnchorPoint={true}        // enable mid-anchor stop
  midAnchorPointPx={250}       // custom mid-anchor height (default: half)
  isAbsolute={true}            // bottom sheets typically overlay
>
  <div>Sheet content</div>
</SwipeBarBottom>

Key Concepts

isAbsolute controls whether the sidebar pushes content or overlays on top. On mobile (below mediaQueryWidth), sidebars automatically switch to absolute positioning regardless of this prop.

mediaQueryWidth sets the breakpoint below which swipe gestures activate. Above this width, sidebars respond only to toggle clicks and programmatic control. Default is 640px.

Viewport reconciliation — whenever the viewport crosses mediaQueryWidth (in either direction), any open sidebar is closed automatically with no animation. The sidebar ends up in the appropriate close-state for the new viewport: fully hidden on mobile, or — if showRail is on — the rail on desktop. This keeps state, overlays, and body scroll lock in sync across resizes.

showRail turns the desktop close-state into a narrow icon column instead of fully hiding. Set railWidthPx to control its width (default 64). Rail items remain interactive; the focus trap only activates in the open mode. On viewports below mediaQueryWidth, rail is suppressed and the sidebar uses the traditional overlay close. The built-in toggle is hidden on desktop while the rail is showing — the rail itself is the affordance.

disabled completely shuts down a sidebar: no swipe gestures, no toggle button, no programmatic control. Set it on the provider to disable everything, or on individual sidebars.

Runtime Updates

The useSwipeBarContext hook exposes globalOptions and setGlobalOptions for changing provider-level settings at runtime. Pass a partial options object and it merges with the current values:

runtime-updates.tsx

const { setGlobalOptions } = useSwipeBarContext();

// Update transition speed at runtime
setGlobalOptions({ transitionMs: 500 });

// Toggle overlay
setGlobalOptions({ showOverlay: false });