ScrollView

ScrollView makes long content scrollable.

👉 Please note that HTML is rendered even when no children are provided. This is needed to allow the auto-scroll feature to work.

Basic Usage

To implement the ScrollView component, you need to import it first:

import { ScrollView } from '@react-ui-org/react-ui';

And use it:

See API for all available options.

General Guidelines

• ScrollView takes up all available horizontal space and expands vertically according to the length of its content. Depending on your layout, you may need to restrict the height of its parent to activate scrolling.

• While arrow controls are optional in the vertical mode, you should always enable arrows in the horizontal mode when the scrollbar is disabled. Because if you don't, users without horizontal-scrolling-enabled devices (like an old-school mouse) might not be able to access your content.

• For dynamic content such as chat window or console output, consider using the auto-scroll feature. This will ensure the newest content is always visible.

• ScrollView enables scrolling on all screen sizes. If you need to make an area in your app scrollable based on viewport size, please use custom CSS with media queries instead.

• ScrollView only supports scrolling in a single direction at a time. It crops content that would possibly overflow in the other direction because additional scrollbars would be unreachable under scrolling shadows. If you need your content to be ready for bi-directional scrolling, either consider using just overflow: auto instead of ScrollView, or make your content scrollable before putting it into ScrollView and make sure its scrollbars don't collide with scrolling shadows.

Arrows

You can suppress the system scrollbar and display arrow controls instead.

Horizontal Scrolling

The horizontal mode is useful when you have (or expect to have) a lot of horizontal content and you need to make sure it remains accessible on all viewport sizes.

Auto Scrolling

ScrollView can watch its content for changes and automatically scroll to the end when the content has changed.

⚠️ The auto-scroll functionality requires all children to have the key property defined because it detects changes of these keys.

Customization

It's possible to entirely customize the arrow controls, including the scroll step, and the scrolling shadows.

Custom Arrows

You can pass any HTML element or even a custom React component to be used as the arrow control. Furthermore, you can change the scroll step if you need to scroll by smaller or bigger portions.

Scrolling Shadows

You can customize the start and end scrolling shadows using startShadow* and endShadow* properties.

Linear Gradients

For easier CSS definition of linear gradients for both vertical and horizontal directions at the same time, there are --rui-local-start-shadow-direction and --rui-local-end-shadow-direction custom properties that can be used inside startShadowBackground and endShadowBackground definitions. The value of the custom properties then reacts to the direction option:

This is useful if you want to create a single definition of linear gradients for scrolling shadows in both directions via global props.

Forwarding HTML Attributes

In addition to the options below in the component's API section, you can specify React synthetic events or any HTML attribute you like. All attributes that don't interfere with the API are forwarded to the <div> HTML element. This enables making the component interactive and helps to improve its accessibility.

👉 Refer to the MDN reference for the full list of supported attributes of the div element.

Forwarding ref

If you provide ref, it is forwarded to the scrolling viewport native HTML <div> element.

API