@octavian-tocan/react-overlay

Unified overlay components for React: BottomSheet with snap points and Modal with animations.

Installation

npm install @octavian-tocan/react-overlay
# or
pnpm add @octavian-tocan/react-overlay
# or
yarn add @octavian-tocan/react-overlay

Peer Dependencies

npm install react react-dom motion clsx tailwind-merge
# Optional: lucide-react (for DismissButton icon)
npm install lucide-react

Quick Start (Copy & Paste)

BottomSheet

import { useState } from "react";
import { BottomSheet } from "@octavian-tocan/react-overlay";

export function MyBottomSheet() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Sheet</button>
      <BottomSheet
        open={open}
        onDismiss={() => setOpen(false)}
        snapPoints={({ maxHeight }) => [200, maxHeight * 0.5, maxHeight * 0.9]}
      >
        <div className="p-4">
          <h2>Sheet Content</h2>
          <p>Drag to resize or swipe down to dismiss.</p>
        </div>
      </BottomSheet>
    </>
  );
}

Modal

import { useState } from "react";
import { Modal, ModalHeader, ModalDescription } from "@octavian-tocan/react-overlay";
import { AlertCircle } from "lucide-react";

export function MyModal() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Open Modal</button>
      <Modal open={open} onDismiss={() => setOpen(false)} size="md">
        <ModalHeader icon={<AlertCircle className="w-4 h-4 text-white" />} title="Confirm Action" />
        <ModalDescription>Are you sure you want to proceed?</ModalDescription>
        <div className="flex gap-2 mt-4 justify-end">
          <button onClick={() => setOpen(false)}>Cancel</button>
          <button
            onClick={() => {
              /* handle confirm */ setOpen(false);
            }}
          >
            Confirm
          </button>
        </div>
      </Modal>
    </>
  );
}

Documentation

• Live Storybook
• API Reference
• Examples
• Architecture
• Migration Guide

Components

BottomSheet

A draggable bottom sheet with snap points, spring animations, and swipe-to-dismiss.

import { BottomSheet } from "@octavian-tocan/react-overlay";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <BottomSheet
      open={open}
      onDismiss={() => setOpen(false)}
      snapPoints={({ maxHeight }) => [200, maxHeight * 0.5, maxHeight * 0.9]}
    >
      <p>Sheet content here</p>
    </BottomSheet>
  );
}

BottomSheet Props

| Prop | Type | Default | Description | | --------------- | ---------------------- | ------------ | ------------------------------------ | | open | boolean | required | Whether the sheet is open | | onDismiss | () => void | required | Called when sheet is dismissed | | children | ReactNode | required | Content to render | | snapPoints | number[] \| Function | [40%, 85%] | Snap points for the sheet | | defaultSnap | number \| Function | last point | Initial snap point | | header | ReactNode | - | Header content above the scroll area | | stickyHeader | ReactNode | - | Sticky header inside the scroll area | | footer | ReactNode | - | Sticky footer content | | scrollLocking | boolean | true | Lock body scroll when open | | testId | string | - | Test ID for testing |

BottomSheet Styling Props

| Prop | Type | Default | Description | | ------------------ | ------------------- | ------- | ------------------------------------- | | className | string | - | CSS class for root overlay | | style | CSSProperties | - | Inline styles for root overlay | | sheetClassName | string | - | CSS class for sheet container | | sheetStyle | CSSProperties | - | Inline styles for sheet container | | handleClassName | string | - | CSS class for handle zone | | handleStyle | CSSProperties | - | Inline styles for handle pill | | contentClassName | string | - | CSS class for scrollable content area | | contentStyle | CSSProperties | - | Inline styles for scrollable content | | unstyled | boolean \| object | - | Remove default styling (see below) |

Unstyled Mode

The unstyled prop removes default backgrounds and padding for full customization:

// Remove all default styling
<BottomSheet unstyled>...</BottomSheet>

// Selectively remove styling
<BottomSheet unstyled={{ sheet: true, content: true, handle: false }}>...</BottomSheet>

| Option | Effect | | --------- | ----------------------------------- | | sheet | Removes white background from sheet | | content | Removes padding from content area | | handle | Hides the drag handle pill |

Gradient Background Example

<BottomSheet
  open={open}
  onDismiss={() => setOpen(false)}
  unstyled={{ sheet: true, content: true }}
  sheetClassName="bg-gradient-to-b from-sky-400 to-sky-600"
  contentClassName="p-6"
>
  <div className="text-white">
    <h2>Sign in to continue</h2>
    <p>Create an account to get started</p>
  </div>
</BottomSheet>

Dark Theme with Custom Handle and Dismiss Button

For dark-themed sheets, use handleStyle to customize the handle pill color and the unstyled dismiss button variant:

<BottomSheet
  open={open}
  onDismiss={() => setOpen(false)}
  unstyled={{ sheet: true, content: true }}
  sheetClassName="bg-gradient-to-br from-gray-900 to-gray-800"
  handleStyle={{ backgroundColor: "rgba(255, 255, 255, 0.5)" }}
  dismissButton={{
    show: true,
    position: "right",
    props: { variant: "unstyled", className: "text-white hover:text-white/80" },
  }}
>
  <div className="text-white p-6">
    <h2>Dark Theme Sheet</h2>
    <p>Custom handle and dismiss button styling</p>
  </div>
</BottomSheet>

Modal

A centered modal dialog with size presets and Motion animations.

import { Modal, ModalHeader, ModalDescription } from "@octavian-tocan/react-overlay";
import { AlertCircle } from "lucide-react";

function App() {
  const [open, setOpen] = useState(false);

  return (
    <Modal open={open} onDismiss={() => setOpen(false)} size="md">
      <ModalHeader icon={<AlertCircle className="w-4 h-4 text-white" />} title="Confirm Action" />
      <ModalDescription>Are you sure you want to proceed?</ModalDescription>
      {/* Your content */}
    </Modal>
  );
}

Modal Props

| Prop | Type | Default | Description | | --------------------- | ---------------------------------------- | -------- | ------------------------------ | | open | boolean | required | Whether the modal is open | | onDismiss | () => void | required | Called when modal is dismissed | | children | ReactNode | required | Content to render | | size | 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' | 'md' | Size preset | | padding | boolean | true | Add default padding | | closeOnOverlayClick | boolean | true | Close on backdrop click | | closeOnEscape | boolean | true | Close on Escape key | | showDismissButton | boolean | true | Show X button | | testId | string | - | Test ID for testing |

ModalWrapper

Low-level modal component for full customization.

import { ModalWrapper } from "@octavian-tocan/react-overlay";

<ModalWrapper
  open={isOpen}
  onDismiss={handleClose}
  contentClassName="bg-white rounded-xl p-8 max-w-lg"
  showDismissButton
>
  {children}
</ModalWrapper>;

Helper Components

ModalHeader

Header with icon badge and title.

import { ModalHeader } from "@octavian-tocan/react-overlay";
import { AlertCircle } from "lucide-react";

<ModalHeader icon={<AlertCircle className="w-4 h-4 text-white" />} title="Confirm Delete" />;

ModalDescription

Styled description text.

import { ModalDescription } from "@octavian-tocan/react-overlay";

<ModalDescription>This action cannot be undone.</ModalDescription>;

DismissButton

Close button for overlays.

import { DismissButton } from "@octavian-tocan/react-overlay";

<DismissButton
  onClick={handleClose}
  variant="default" // "default", "subtle", or "unstyled"
  position="absolute top-3 right-3"
/>;

| Variant | Description | | ---------- | -------------------------------------------------------- | | default | White background, border, shadow - for light backgrounds | | subtle | White background, no border - for banners | | unstyled | No background/border/shadow - for dark backgrounds |

Hooks

useBodyScrollLock

Lock body scroll when an overlay is open. Supports multiple concurrent overlays via ref-counting.

import { useBodyScrollLock } from "@octavian-tocan/react-overlay";

function MyOverlay({ isOpen }) {
  useBodyScrollLock(isOpen);
  return isOpen ? <div>Overlay content</div> : null;
}

Utilities

cn

Class name utility (clsx + tailwind-merge) for conditional classes.

import { cn } from "@octavian-tocan/react-overlay";

<div className={cn("base-class", isActive && "active-class", className)} />;

TypeScript

Full TypeScript support with exported types:

import type {
  BottomSheetProps,
  BottomSheetRef,
  ModalProps,
  ModalWrapperProps,
  ModalSize,
  ModalHeaderProps,
  ModalDescriptionProps,
  DismissButtonProps,
} from "@octavian-tocan/react-overlay";

Custom Scrollbar Styling

The package includes optional CSS for custom scrollbar styling on scrollable content.

Setup

Import the CSS file once in your app entry point:

// In your app entry (e.g., main.tsx, App.tsx)
import "@octavian-tocan/react-overlay/styles/scrollbar.css";

Customization

Override CSS variables to match your theme:

:root {
  --ro-scrollbar-thumb: #6366f1; /* Scrollbar color */
  --ro-scrollbar-thumb-hover: #4f46e5; /* Hover color */
  --ro-scrollbar-width: 6px; /* Width */
  --ro-scrollbar-track: transparent; /* Track color */
}

Usage

• BottomSheet: Scrollbar styling applied automatically
• ModalWrapper: Applied when scrollable={true} (default)
• Custom elements: Add data-ro-scroll attribute

<div data-ro-scroll className="overflow-auto max-h-96">
  Scrollable content with custom styling
</div>

License

MIT © Octavian Tocan