ScrollLock

The @bento/scroll-lock package provides both a ScrollLock component and a
useScrollLock hook that prevent background scrolling while overlays, modals,
or other UI elements require user focus. This primitive wraps React Aria's
usePreventScroll hook, adding Bento-specific data attributes for debugging and
styling.

Installation

``bash
npm install --save @bento/scroll-lock
`

Props

The following properties are available to be used on the ScrollLock component:

| Prop | Type | Required | Description |
|------|------|----------|------------|
| children | ReactNode | No | Optional children to render.
ScrollLock doesn't render any DOM elements, so children are optional. |
| slot | string | No | A named part of a component that can be customized. This is implemented by the consuming component.
The exposed slot names of a component are available in the components documentation. |
| slots | Record | No | An object that contains the customizations for the slots.
The main way you interact with the slot system as a consumer. |
| isDisabled | boolean | No | Whether scroll locking is disabled.
When true, scrolling is not prevented. |

Examples

$3

The simplest usage is to render the ScrollLock component. It will prevent
scrolling while mounted.

$3

For more control or when building custom components, use the useScrollLock
hook directly.

$3

ScrollLock is commonly used with modals and overlays to prevent background
scrolling while the overlay is active.

Accessibility

The ScrollLock component automatically handles accessibility features:

- Screen Reader Compatibility: Doesn't interfere with virtual cursor navigation
- Focus Management Integration: Works seamlessly with React Aria's useFocusScope and useModal
- Keyboard Support: Properly handles all keyboard-based scrolling methods
- Touch Accessibility: Maintains touch event handling on mobile devices while preventing scroll

React Aria Integration

ScrollLock wraps React Aria's usePreventScroll hook, which provides
comprehensive scroll prevention including scrollbar compensation, mobile
support, and proper cleanup. The Bento wrapper adds data attributes for
debugging and provides a consistent API with other Bento hooks and components.

Customization

$3

ScrollLock is created using the @bento/slots package and supports the standard
slot and slots props for integration with parent components. Since
ScrollLock doesn't render DOM elements, it doesn't define internal slot
assignments.

See the @bento/slots package for more information on how to use the slot and
slots properties.

$3

Since ScrollLock doesn't render any DOM elements, styling is applied through the
data attributes it adds to document.body. You can use these attributes to
style your application based on scroll lock state.

The following data attributes are applied to document.body:

| Attribute | Description | Example Values |
| -------------------- | ------------------------------------- | -------------- |
| data-scroll-locked | Indicates when scroll lock is active | "true" |

These data attributes can be targeted in your CSS:

`css
body[data-scroll-locked="true"] {
/ Styles when scroll is locked /
}
`

Server-Side Rendering

ScrollLock is SSR-safe and will not execute scroll prevention logic on the
server. The component and hook check for the existence of document` before
applying scroll prevention, ensuring compatibility with server-side rendering
environments.