SwipeBar

A native swipe bar experience

SwipeBar provides an intuitive, native-app-like experience for mobile and desktop sidebars. Swipe from the edge to open, drag to close, and enjoy smooth animations with full customization control.

Features

- 📦 Lightweight - zero dependencies
- 📱 Native Mobile Gestures - Swipe from screen edges just like native apps
- 🖱️ Desktop Support - Works seamlessly with mouse interactions
- 🎨 Fully Customizable - Complete control over styling, animations, and behavior
- 🎯 Smart Positioning - Automatically adapts between absolute and relative positioning
- 🎭 Custom Toggles - Use built-in toggle icons or provide your own components
- ⚡ Performant - Relies on transform and opacity properties
- 🎚️ Configurable Thresholds - Fine-tune edge activation and drag sensitivity
- 🌓 Overlay Support - Optional backdrop overlay with customizable colors
- 📏 Responsive - Media query support for different screen sizes
- 🔧 Programmatic Control - Open and close sidebars from anywhere in your app

Installation

``bash
npm install @luciodale/swipe-bar


or

`bash
npm install @luciodale/swipe-bar
`

$3

Wrap your app with SwipeBarProvider:

`tsx
import { SwipeBarProvider } from "@luciodale/swipe-bar";

function App() {
return (

{/ Your app content /}

);
}
`

$3

`tsx
import { SwipeBarLeft } from "@luciodale/swipe-bar";

`tsx
import { SwipeBarRight } from "@luciodale/swipe-bar";

`tsx
import { useSwipeBarContext } from "@luciodale/swipe-bar";

function MyComponent() {
const { openSidebar, closeSidebar, isLeftOpen, isRightOpen } = useSwipeBarContext();

return (
openSidebar("left")}>
Open Left Sidebar

);
}
`

Props & Configuration

$3

Configure global defaults for all sidebars:

`tsx
sidebarWidthPx={320}
transitionMs={300}
edgeActivationWidthPx={40}
dragActivationDeltaPx={20}
showOverlay={true}
isAbsolute={false}
overlayBackgroundColor="rgba(0, 0, 0, 0.5)"
toggleIconColor="white"
toggleIconSizePx={40}
toggleIconEdgeDistancePx={40}
showToggle={true}
mediaQueryWidth={640}
swipeBarZIndex={30}
toggleZIndex={15}
overlayZIndex={20}
>
{children}

`

$3

Both SwipeBarLeft and SwipeBarRight accept the same props, which override provider defaults:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| className | string | - | CSS classes for the sidebar container |
| ToggleComponent | ReactNode | - | Custom toggle button component |
| sidebarWidthPx | number | 320 | Width of the sidebar in pixels |
| transitionMs | number | 200 | Animation duration in milliseconds |
| edgeActivationWidthPx | number | 40 | Touch zone width from screen edge to activate swipe |
| dragActivationDeltaPx | number | 20 | Minimum drag distance to activate sidebar |
| showOverlay | boolean | true | Show backdrop overlay when sidebar is open |
| isAbsolute | boolean | false | Use absolute positioning (overlay mode) |
| overlayBackgroundColor | string | "rgba(0, 0, 0, 0.5)" | Overlay background color |
| toggleIconColor | string | "white" | Color of the built-in toggle icon |
| toggleIconSizePx | number | 40 | Size of the toggle icon |
| toggleIconEdgeDistancePx | number | 40 | Distance of toggle from screen edge |
| showToggle | boolean | true | Show the toggle button |
| mediaQueryWidth | number | 640 | Max screen width for swipe gestures (in pixels) |
| swipeBarZIndex | number | 30 | Z-index for left and right swipe bars |
| toggleZIndex | number | 15 | Z-index for left and right toggle buttons |
| overlayZIndex | number | 20 | Z-index for the overlay backdrop |

$3

`tsx
const {
isLeftOpen, // boolean - is left sidebar open
isRightOpen, // boolean - is right sidebar open
openSidebar, // (side: "left" | "right") => void
closeSidebar, // (side: "left" | "right") => void
globalOptions, // current global options
setGlobalOptions, // update global options
} = useSwipeBarContext();
`

Key Concepts

$3

By default, sidebars push content to the side. Set isAbsolute={true} to make sidebars overlay on top of content instead:

`tsx

{/ This sidebar will overlay content /}

`

Note: On mobile (below mediaQueryWidth), sidebars automatically switch to absolute positioning for a better mobile experience.

$3

Control when swipe gestures are enabled based on screen size:

`tsx

{/ Swipe gestures only work on screens ≤640px wide /}

`

This is useful if you want swipe interactions only on mobile/tablet devices.

$3

The built-in toggle button automatically hides when:
- The overlay is visible to handle closing instead

$3

Replace the default toggle with your own component:

`tsx
ToggleComponent={

☰

}
>
{/ content /}

`

Examples

$3

`tsx
import { SwipeBarProvider, SwipeBarLeft } from "@luciodale/swipe-bar";

function App() {
return (




Navigation

`tsx
className="bg-white/10 backdrop-blur-2xl border-r border-white/20"
overlayBackgroundColor="rgba(0, 0, 0, 0.3)"
>
{/ Glass effect sidebar content /}

`

$3

`tsx
sidebarWidthPx={window.innerWidth}
isAbsolute={true}
>
{/ Full screen mobile menu /}

`

$3

`tsx
function Header() {
const { openSidebar } = useSwipeBarContext();

return (


Browser Support

- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- Mobile Safari (iOS 12+)
- Chrome Android (latest)

Touch events and smooth animations are supported across all modern browsers.

Contributing

Contributions are welcome! Feel free to:

- Report bugs
- Suggest new features
- Submit pull requests
- Improve documentation

License

MIT