@slithy/modal-spring

@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