@slithy/modal-spring

Animated modal adapter for @slithy/modal-kit, built on react-spring and @use-gesture/react.

Provides animated enter/leave transitions, an animated backdrop, and drag-to-close gesture support.

Installation

pnpm add @slithy/modal-core @slithy/modal-kit @slithy/modal-spring
pnpm add "@react-spring/web@>=9 <10" @use-gesture/react

@react-spring/web (v9.x) and @use-gesture/react are peer dependencies. react-spring v10 is not yet supported.

Setup

import { LayerProvider, LayerStackPriority } from '@slithy/layers'
import { Portal } from '@slithy/portal'
import { ModalRenderer } from '@slithy/modal-spring'

export function App() {
  return (
    <LayerProvider id="app" zIndex={LayerStackPriority.Base}>
      <main>{/* your app */}</main>
      <ModalRenderer
        renderLayer={(children) => (
          <LayerProvider id="modal" zIndex={LayerStackPriority.Modal}>
            {children}
          </LayerProvider>
        )}
        renderPortal={(children) => <Portal>{children}</Portal>}
      />
    </LayerProvider>
  )
}

renderLayer and renderPortal are optional — omit them if you don't use @slithy/layers or @slithy/portal.

Usage

import { useModalStore } from '@slithy/modal-core'
import { Modal } from '@slithy/modal-spring'

function MyButton() {
  const open = (event: React.MouseEvent) => {
    useModalStore.getState().openModal(
      <Modal aria-label="My Modal">
        <p>Content</p>
      </Modal>,
      { triggerEvent: event }
    )
  }
  return <button onClick={open}>Open</button>
}

Modal Props

| Prop | Type | Default | Description | |---|---|---|---| | aria-label | string | — | Accessible name for the dialog | | alignX | 'center' \| 'left' \| 'right' | 'center' | Horizontal position | | alignY | 'middle' \| 'top' \| 'bottom' | 'middle' | Vertical position | | dismissible | boolean | true | Allow Escape and backdrop-click to close | | contentClassName | string | — | Class on the <dialog> element | | contentStyle | CSSProperties | — | Static styles on the <dialog> element | | contentTransitions | { from, enter, leave } | — | Spring transition values | | disableOpacityTransition | boolean | — | Skip the default opacity fade | | dragDirection | DragDirection | — | Enable drag-to-close | | containerScrolling | boolean | true | Allow container scroll | | layerIsActive | boolean | true | Pass from useLayerState for layer coordination | | springConfig | SpringConfig | — | Override the default spring config | | afterOpen | () => void | — | Fires after enter animation completes | | afterClose | () => void | — | Fires after modal is removed |

Exports

| Export | Description | |---|---| | Modal | Animated modal component | | ModalProps | — | | ModalRenderer | Renders all open modals with animated backdrop | | ModalBackdrop | Animated backdrop (used by ModalRenderer) | | DragHandle | Drag-to-close gesture wrapper | | useModalDrag | Low-level drag hook | | useModalDragging | Internal drag spring hook | | defaultSpring | Default spring config | | iosSheetSpring | iOS-feel spring config | | DragDirection | 'up' \| 'down' \| 'left' \| 'right' | | DragStyles | Spring transform values from drag |