Edit page

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:

Custom propertyVertical directionHorizontal direction
--rui-local-start-shadow-directionto bottomto right
--rui-local-end-shadow-directionto topto left

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

API

Prop nameTypeDefaultRequiredDescription
arrowsboolfalsefalse

If true, display the arrow controls.

arrowsScrollStepnumber200false

Portion to scroll by when the arrows are clicked, in px.

autoScroll'always' │ 'detectEnd' │ 'off''off'false

The auto-scroll mechanism requires having the key prop set for every child present in children because it detects changes of those keys. Without the keys, the auto-scroll will not work.

Option always means the auto-scroll scrolls to the end every time the content changes. Option detectEnd means the auto-scroll scrolls to the end only when the content is changed and the user has scrolled at the end of the viewport at the moment of the change.

See https://reactjs.org/docs/lists-and-keys.html#keys

childrennodenullfalse

Content to be scrollable.

debouncenumber50false

Delay in ms before the display of arrows and scrolling shadows is evaluated during interaction.

direction'horizontal' │ 'vertical''vertical'false

Direction of scrolling.

endShadowBackgroundstring"linear-gradient(var(--rui-local-end-shadow-direction), rgba(255 255 255 / 1), rgba(255 255 255 / 0))"false

Custom background of the end scrolling shadow. Can be a CSS gradient or an image url().

endShadowInitialOffsetstring"-1rem"false

Initial offset of the end scrolling shadow (transitioned). If set, the end scrolling shadow slides in by this distance.

endShadowSizestring"2em"false

Size of the end scrolling shadow. Accepts any valid CSS length value.

idstringundefinedfalse

ID of the root HTML element. It also serves as base for nested elements:

  • <ID>__content
  • <ID>__arrowPrevButton
  • <ID>__arrowNextButton
nextArrowColorstringundefinedfalse

Text color of the end arrow control. Accepts any valid CSS color value.

nextArrowElementnodenullfalse

Custom HTML or React Component to replace the default next-arrow control.

nextArrowInitialOffsetstring"-0.5rem"false

Initial offset of the end arrow control (transitioned). If set, the next arrow slides in by this distance.

prevArrowColorstringundefinedfalse

Text color of the start arrow control. Accepts any valid CSS color value.

prevArrowElementnodenullfalse

Custom HTML or React Component to replace the default prev-arrow control.

prevArrowInitialOffsetstring"-0.5rem"false

Initial offset of the start arrow control (transitioned). If set, the prev arrow slides in by this distance.

scrollbarbooltruefalse

If false, the system scrollbar will be hidden.

shadowsbooltruefalse

If true, display scrolling shadows.

startShadowBackgroundstring"linear-gradient(var(--rui-local-start-shadow-direction), rgba(255 255 255 / 1), rgba(255 255 255 / 0))"false

Custom background of the start scrolling shadow. Can be a CSS gradient or an image url().

startShadowInitialOffsetstring"-1rem"false

Initial offset of the start scrolling shadow (transitioned). If set, the start scrolling shadow slides in by this distance.

startShadowSizestring"2em"false

Size of the start scrolling shadow. Accepts any valid CSS length value.