Ark UI Logo
Components
Scroll area

Scroll Area

A custom scrollable area component with styled scrollbars.

Loading...

Features

  • Cross-browser custom scrollbars
  • Native scroll behavior
  • Keyboard navigation support
  • Touch and mouse support
  • Horizontal and vertical scrolling
  • Support for nested scroll areas
  • Customizable scrollbar appearance

Anatomy

To set up the scroll area correctly, it's essential to understand its anatomy and the naming of its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Required style

It's important to note that the scroll area requires the following styles on the ScrollArea.Viewport element to hide the native scrollbar:

[data-scope='scroll-area'][data-part='viewport'] {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

Examples

Basic Usage

Create a basic scrollable area with custom scrollbar.

import { ScrollArea } from '@ark-ui/react/scroll-area'

export const Basic = () => (
  <ScrollArea.Root style={{ height: '8.5rem' }}>
    <ScrollArea.Viewport style={{ height: '100%' }}>
      <ScrollArea.Content style={{ padding: '1rem 1rem 1.5rem' }}>
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore
          magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
          consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
          pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id
          est laborum. Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium,
          totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt
          explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur
          magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia
          dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et
          dolore magnam aliquam quaerat voluptatem.
        </p>
      </ScrollArea.Content>
    </ScrollArea.Viewport>
    <ScrollArea.Scrollbar>
      <ScrollArea.Thumb />
    </ScrollArea.Scrollbar>
    <ScrollArea.Corner />
  </ScrollArea.Root>
)

Horizontal Scrolling

Configure the scroll area for horizontal scrolling only.

import { ScrollArea } from '@ark-ui/react/scroll-area'

export const Horizontal = () => (
  <ScrollArea.Root style={{ width: '50%' }}>
    <ScrollArea.Viewport>
      <ScrollArea.Content style={{ padding: '1rem 1rem 1.5rem' }}>
        <p style={{ width: '70vw' }}>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore
          magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
          consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla
          pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id
          est laborum.
        </p>
      </ScrollArea.Content>
    </ScrollArea.Viewport>
    <ScrollArea.Scrollbar orientation="horizontal">
      <ScrollArea.Thumb />
    </ScrollArea.Scrollbar>
    <ScrollArea.Corner />
  </ScrollArea.Root>
)

Both Directions

Enable scrolling in both horizontal and vertical directions.

import { ScrollArea } from '@ark-ui/react/scroll-area'

export const BothDirections = () => (
  <ScrollArea.Root style={{ height: '300px', width: '300px' }}>
    <ScrollArea.Viewport style={{ width: '100%', height: '100%' }}>
      <ScrollArea.Content style={{ padding: '1rem' }}>
        <div style={{ width: '50vw' }}>
          <p>
            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et
            dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex
            ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat
            nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit
            anim id est laborum.
          </p>
          <p>
            Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem
            aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.
            Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni
            dolores eos qui ratione voluptatem sequi nesciunt.
          </p>
          <p>
            At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti
            atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident, similique
            sunt in culpa qui officia deserunt mollitia animi, id est laborum et dolorum fuga.
          </p>
        </div>
      </ScrollArea.Content>
    </ScrollArea.Viewport>
    <ScrollArea.Scrollbar orientation="vertical">
      <ScrollArea.Thumb />
    </ScrollArea.Scrollbar>
    <ScrollArea.Scrollbar orientation="horizontal">
      <ScrollArea.Thumb />
    </ScrollArea.Scrollbar>
    <ScrollArea.Corner />
  </ScrollArea.Root>
)

Nested Scroll Areas

Scroll areas can be nested within each other for complex layouts.

import { ScrollArea } from '@ark-ui/react/scroll-area'

export const Nested = () => (
  <ScrollArea.Root style={{ height: '12rem', width: '50%' }}>
    <ScrollArea.Viewport style={{ height: '100%' }}>
      <ScrollArea.Content style={{ padding: '1rem 1rem 1.5rem' }}>
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore
          magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
          consequat.
        </p>
        <ScrollArea.Root style={{ height: '8rem' }}>
          <ScrollArea.Viewport style={{ height: '100%' }}>
            <ScrollArea.Content style={{ padding: '1rem 1rem 1.5rem' }}>
              <p>
                This is a nested scroll area. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
                dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui
                officia deserunt mollit anim id est laborum. Sed ut perspiciatis unde omnis iste natus error sit
                voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore
                veritatis et quasi architecto beatae vitae dicta sunt explicabo.
              </p>
            </ScrollArea.Content>
          </ScrollArea.Viewport>
          <ScrollArea.Scrollbar>
            <ScrollArea.Thumb />
          </ScrollArea.Scrollbar>
          <ScrollArea.Corner />
        </ScrollArea.Root>
      </ScrollArea.Content>
    </ScrollArea.Viewport>
    <ScrollArea.Scrollbar>
      <ScrollArea.Thumb />
    </ScrollArea.Scrollbar>
    <ScrollArea.Corner />
  </ScrollArea.Root>
)

API Reference

Root

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
ids
Partial<{ root: string; viewport: string; content: string; scrollbar: string; thumb: string }>

The ids of the scroll area elements

Data AttributeValue
[data-scope]scroll-area
[data-part]root
[data-overflow-x]Present when the content overflows the x-axis
[data-overflow-y]Present when the content overflows the y-axis

Content

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]scroll-area
[data-part]content
[data-overflow-x]Present when the content overflows the x-axis
[data-overflow-y]Present when the content overflows the y-axis

Corner

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]scroll-area
[data-part]corner
[data-state]"hidden" | "visible"
[data-overflow-x]Present when the content overflows the x-axis
[data-overflow-y]Present when the content overflows the y-axis

RootProvider

PropDefaultType
value
UseScrollAreaReturn

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Scrollbar

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
orientation
Orientation

Data AttributeValue
[data-scope]scroll-area
[data-part]scrollbar
[data-orientation]The orientation of the scrollbar
[data-scrolling]Present when scrolling
[data-hover]Present when hovering
[data-overflow-x]Present when the content overflows the x-axis
[data-overflow-y]Present when the content overflows the y-axis

Thumb

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]scroll-area
[data-part]thumb
[data-orientation]The orientation of the thumb

Viewport

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
Data AttributeValue
[data-scope]scroll-area
[data-part]viewport
[data-at-top]Present when scrolled to the top edge
[data-at-bottom]Present when scrolled to the bottom edge
[data-at-left]Present when scrolled to the left edge
[data-at-right]Present when scrolled to the right edge
[data-overflow-x]Present when the content overflows the x-axis
[data-overflow-y]Present when the content overflows the y-axis