# ScrollArea

- Page: https://jiguang132.com/resources/mantine/docs/scroll-area
- Resource: Mantine Core (https://jiguang132.com/resources/mantine.md)
- All guides: https://jiguang132.com/resources/mantine/docs.md

Install: `npm install @mantine/core@9.7.1 @mantine/hooks@9.7.1`

## Version and compatibility

Pinned Mantine Core 9.7.1 requires React and React DOM `^19.2.0` and matching `@mantine/hooks@9.7.1`, from the installed npm package's peerDependencies. Do not force it into React 18 or another incompatible version. Explain upgrade impact and agree on a plan with the project owner; do not hide conflicts with --force/--legacy-peer-deps. The native Provider enables `theme.respectReducedMotion` and uses `forceColorScheme` for light/dark.

## Use case

Constrain scrolling to a sized content region.

## Native props used by this example

These props are extracted from the local typechecked JSX and grouped by their owning native component. This is not an exhaustive prop list; see pinned source signatures and inheritance below.

| Component prop | Explanation |
| --- | --- |
| `ScrollArea.h` | Mantine height style prop. |
| `ScrollArea.w` | Mantine width style prop. |

## Interaction and state checks

Current scenarios: Default. Check actual behavior after selecting supported disabled/error/read-only scenarios; components without those native states do not receive invented universal props. Verify keyboard focus and exits, then connect changed values through the native callback signature.

## Business integration boundary

Demo content/state is local, without server persistence, authorization or fetching. A static display component is not a completed business workflow.

## Host setup

Install pinned @mantine/core and @mantine/hooks, import @mantine/core/styles.css at the entry and use MantineProvider. The example's theme/variant are JGuang-authored host props, not universal native component APIs; forceColorScheme synchronizes the app theme. Native implementation source is a reading reference: use npm exports rather than copying internal engines. This batch covers Core, not dates/charts/forms extension packages. Detailed upstream prose remains English.


## Runnable usage

```tsx
import { useState } from 'react';
import * as M from '@mantine/core';
import '@mantine/core/styles.css';


function ComponentPreview({ variant = 'Default' }: { variant?: string }) {

return <M.ScrollArea h={150} w={300}>{Array.from({ length: 15 }, (_, i) => <M.Text key={i}>Scrollable item {i + 1}</M.Text>)}</M.ScrollArea>;
}
export default function Example({ variant = 'Default', theme = 'light' }: { variant?: string; theme?: 'light' | 'dark' }) {
return <M.MantineProvider forceColorScheme={theme} theme={{ respectReducedMotion: true }}><ComponentPreview variant={variant} /></M.MantineProvider>;
}

```


## Preview states

Default

The example uses the native Mantine API. For supported input demos, change the local variant to Disabled, Invalid or Read only; these are example labels, not new component props. Keep the documented data, controlled values, stores and compound children when adapting the example.



## Usage

The `ScrollArea` component supports the following props:

- `type` defines scrollbars behavior:
  - `hover` – scrollbars are visible on hover
  - `scroll` – scrollbars are visible on scroll
  - `auto` – similar to `overflow: auto` – scrollbars are always visible when the content is overflowing
  - `always` – same as `auto`, but scrollbars are always visible regardless of whether the content is overflowing
  - `never` – scrollbars are always hidden
- `offsetScrollbars` – adds padding to offset scrollbars with the following options:
  - `true` – adds padding to offset both scrollbars
  - `x` – adds padding to offset horizontal scrollbar only
  - `y` – adds padding to offset vertical scrollbar only
  - `present` – adds padding only when scrollbars are visible
- `scrollbarSize` – scrollbar size, controls scrollbar and thumb width/height
- `scrollHideDelay` – delay in ms to hide scrollbars, applicable only when type is `hover` or `scroll`
- `overscrollBehavior` – controls [overscroll-behavior](https://developer.mozilla.org/en-US/docs/Web/CSS/overscroll-behavior) of the viewport



## Horizontal scrollbars



## Disable horizontal scrollbars

To disable horizontal scrollbars, set the `scrollbars="y"` prop:



## Vertical scrollbar position

By default, the vertical scrollbar follows the inline-end edge: it is rendered on the right side
in LTR and on the left side in RTL. Set the `verticalScrollbarPosition` prop to `left` or `right`
to pin the vertical scrollbar to a physical side regardless of direction.

This is useful for RTL applications where users expect the vertical scrollbar to stay on the right,
matching the behavior of most desktop software (Windows, Office, Gmail, etc.). The prop also
realigns the offset padding, the corner and the horizontal scrollbar gap, so it works correctly
with `offsetScrollbars` and `scrollbars="xy"`. When the prop is omitted, the default
direction-based behavior is preserved.



## Subscribe to scroll position changes

Set the `onScrollPositionChange` function to subscribe to scroll position changes.
It will be called each time the user scrolls with x and y coordinates:



## Scroll boundary callbacks

`ScrollArea` component supports callbacks that are triggered when scrolling reaches boundaries:



## Scroll to position

To programmatically scroll to any position,
get the viewport element ref with the `viewportRef` prop and call the `scrollTo` method:



## Start scroll position

Use the `startScrollPosition` prop to set the initial scroll position when the component mounts.
Unlike using `viewportRef` with `useEffect`, this approach avoids the flash of content at position (0, 0):



## Styles API



## Scroll element into view



## ScrollArea.Autosize

`ScrollArea.Autosize` component allows to create scrollable containers when given max-height is reached.
It also supports a callback for detecting when vertical overflow occurs:

- onOverflowChange – triggered when content exceeds max-height, making the container scrollable or not



## ScrollArea.Autosize with Popover




## Source-backed parameter reference

Implementation signatures and types are generated from the pinned local source. Optional props, native inherited types, union branches and never exclusions are preserved. A forwardRef implementation's ref is a React reference, not an additional business prop.


```ts
ScrollArea(_props)
```



```ts
export type ScrollAreaStylesNames =
  | 'root'
  | 'viewport'
  | 'scrollbar'
  | 'thumb'
  | 'corner'
  | 'content';

export type ScrollAreaCssVariables = {
  root: '--scrollarea-scrollbar-size';
};

export interface ScrollAreaProps
  extends BoxProps, StylesApiProps<ScrollAreaFactory>, ElementProps<'div'> {
  /** Scrollbar size, any valid CSS value for width/height, numbers are converted to rem, default value is 12px (0.75rem) */
  scrollbarSize?: number | string;

  /**
   * Defines scrollbars behavior
   * - `'hover'` – scrollbars visible on hover (default)
   * - `'scroll'` – scrollbars visible during scrolling
   * - `'auto'` – scrollbars visible only when content overflows (like CSS overflow: auto)
   * - `'always'` – scrollbars always visible, even when content doesn't overflow
   * - `'never'` – scrollbars always hidden
   * @default 'hover'
   * */
  type?: 'auto' | 'always' | 'scroll' | 'hover' | 'never';

  /** Scroll hide delay in ms, applicable only when type is set to `hover` or `scroll` @default 1000 */
  scrollHideDelay?: number;

  /**
   * Axis at which scrollbars must be rendered
   * - `'x'` - horizontal scrollbar only
   * - `'y'` - vertical scrollbar only
   * - `'xy'` - both scrollbars
   * - `false` - no scrollbars rendered (content remains scrollable via mouse/touch)
   * @default 'xy'
   */
  scrollbars?: 'x' | 'y' | 'xy' | false;

  /**
   * Determines whether scrollbars should be offset with padding on given axis
   * - `true` - adds padding to offset both scrollbars (always)
   * - `'x'` - adds padding to offset horizontal scrollbar (always)
   * - `'y'` - adds padding to offset vertical scrollbar (always)
   * - `'present'` - adds padding only when scrollbars are visible (dynamic)
   * @default false
   */
  offsetScrollbars?: boolean | 'x' | 'y' | 'present';

  /** Assigns viewport element (scrollable container) ref */
  viewportRef?: React.Ref<HTMLDivElement>;

  /** Props passed down to the viewport element */
  viewportProps?: React.ComponentProps<'div'>;

  /** Called with current position (`x` and `y` coordinates) when viewport is scrolled */
  onScrollPositionChange?: (position: { x: number; y: number }) => void;

  /**
   * Called when scrollarea is scrolled to the bottom (within 0.8px tolerance for sub-pixel rendering)
   */
  onBottomReached?: () => void;

  /** Called when scrollarea is scrolled all the way to the top */
  onTopReached?: () => void;

  /** Called when scrollarea is scrolled to the left (within 0.8px tolerance for sub-pixel rendering) */
  onLeftReached?: () => void;

  /** Called when scrollarea is scrolled to the right (within 0.8px tolerance for sub-pixel rendering) */
  onRightReached?: () => void;

  /** Defines `overscroll-behavior` of the viewport */
  overscrollBehavior?: React.CSSProperties['overscrollBehavior'];

  /** Initial scroll position set on mount */
  startScrollPosition?: { x?: number; y?: number };

  /**
   * Pins the vertical scrollbar to a physical side (`left` or `right`) regardless of direction.
   * By default, the scrollbar follows the inline-end edge (right in LTR, left in RTL).
   */
  verticalScrollbarPosition?: 'left' | 'right';
}

export type ScrollAreaFactory = Factory<{
  props: ScrollAreaProps;
  ref: HTMLDivElement;
  stylesNames: ScrollAreaStylesNames;
  vars: ScrollAreaCssVariables;
  staticComponents: {
    Autosize: typeof ScrollAreaAutosize;
  };
}>;

export type Mod = Record<string, any> | string;

export type BoxMod = Mod | Mod[] | BoxMod[];

export interface BoxProps extends MantineStyleProps {
  /** Class added to the root element, if applicable */
  className?: string | undefined;

  /** Inline style added to root component element, can subscribe to theme defined on MantineProvider */
  style?: MantineStyleProp;

  /** CSS variables defined on root component element */
  __vars?: CssVarsProp;

  /** `size` property passed down the HTML element */
  __size?: string;

  /** Breakpoint above which the component is hidden with `display: none` */
  hiddenFrom?: MantineBreakpoint;

  /** Breakpoint below which the component is hidden with `display: none` */
  visibleFrom?: MantineBreakpoint;

  /** Determines whether component should be hidden in light color scheme with `display: none` */
  lightHidden?: boolean;

  /** Determines whether component should be hidden in dark color scheme with `display: none` */
  darkHidden?: boolean;

  /** Element modifiers transformed into `data-` attributes, for example, `{ 'data-size': 'xl' }`, falsy values are removed */
  mod?: BoxMod;
}

export type ElementProps<
  ElementType extends React.ElementType,
  PropsToOmit extends string = never,
> = Omit<React.ComponentProps<ElementType>, 'style' | PropsToOmit>;

export interface CSSProperties extends React.CSSProperties {
  [key: string]: any;
}

type MantineStyle = CSSProperties | ((theme: MantineTheme) => CSSProperties);

export type MantineStyleProp = MantineStyle | MantineStyle[] | MantineStyleProp[] | undefined;

export type CssVariable = `--${string}`;

export type CssVariables<Variable extends string = CssVariable> = Partial<Record<Variable, string>>;

export type CssVars<Variable extends string = CssVariable> =
  | CssVariables<Variable>
  | ((theme: MantineTheme) => CssVariables<Variable>)
  | CssVars<Variable>[];

export type CssVarsProp<Variable extends string = CssVariable> =
  | CssVars<Variable>
  | CssVars<Variable>[];
```


### Native and external types

External types remain defined by React or native dependencies, not manually expanded into guessed props. The installed version's TypeScript definitions are authoritative.


```ts
Factory<{
  props: ScrollAreaProps;
  ref: HTMLDivElement;
  stylesNames: ScrollAreaStylesNames;
  vars: ScrollAreaCssVariables;
  staticComponents: {
    Autosize: typeof ScrollAreaAutosize;
  };
}>
MantineStyleProps
React.CSSProperties
MantineTheme
Partial<Record<Variable, string>>
Record<Variable, string>
Variable
MantineBreakpoint
Record<string, any>
StylesApiProps<ScrollAreaFactory>
React.ElementType
Omit<React.ComponentProps<ElementType>, 'style' | PropsToOmit>
React.ComponentProps<ElementType>
ElementType
PropsToOmit
React.Ref<HTMLDivElement>
HTMLDivElement
React.ComponentProps<'div'>
```

---

Index of all JGuang resources: https://jiguang132.com/llms.txt