> Markdown version of [Scroller](https://vaadin.com/docs/v24/components/scroller). Section index: [llms.txt](https://vaadin.com/docs/v24/components/llms.txt)

# Scroller

Scroller is a container component that enables scrollable areas within the UI.

**Lit** — `scroller-basic.ts`

```typescript
<vaadin-scroller class="border-b p-m" scroll-direction="vertical">
  <section aria-labelledby="personal-title">
    <h3 class="text-l" id="personal-title">Personal information</h3>
    <vaadin-text-field class="w-full" label="First name"></vaadin-text-field>
    <vaadin-text-field class="w-full" label="Last name"></vaadin-text-field>
    <vaadin-date-picker
      class="w-full"
      initial-position="1990-01-01"
      label="Birthdate"
    ></vaadin-date-picker>
  </section>
  <section aria-labelledby="employment-title">
    <h3 class="mt-l text-l" id="employment-title">Employment information</h3>
    <vaadin-text-field class="w-full" label="Position"></vaadin-text-field>
    <vaadin-text-area class="w-full" label="Additional information"></vaadin-text-area>
  </section>
</vaadin-scroller>
```

**Flow** — `ScrollerBasic.java`

```java
// Personal information
H3 personalTitle = new H3("Personal information");
personalTitle.addClassNames(LumoUtility.FontSize.LARGE);
personalTitle.setId(PERSONAL_TITLE_ID);

TextField firstName = new TextField("First name");
firstName.setWidthFull();

TextField lastName = new TextField("Last name");
lastName.setWidthFull();

DatePicker birthDate = new DatePicker("Birthdate");
birthDate.setInitialPosition(LocalDate.of(1990, 1, 1));
birthDate.setWidthFull();

Section personalInformation = new Section(personalTitle, firstName,
        lastName, birthDate);
personalInformation.getElement().setAttribute("aria-labelledby",
        PERSONAL_TITLE_ID);

// Employment information
H3 employmentTitle = new H3("Employment information");
employmentTitle.addClassNames(LumoUtility.FontSize.LARGE, LumoUtility.Margin.Top.LARGE);
employmentTitle.setId(EMPLOYMENT_TITLE_ID);

TextField position = new TextField("Position");
position.setWidthFull();

TextArea additionalInformation = new TextArea("Additional Information");
additionalInformation.setWidthFull();

Section employmentInformation = new Section(employmentTitle, position,
        additionalInformation);
employmentInformation.getElement().setAttribute("aria-labelledby",
        EMPLOYMENT_TITLE_ID);

Scroller scroller = new Scroller(new Div(personalInformation, employmentInformation));
scroller.addClassNames(LumoUtility.Border.BOTTOM, LumoUtility.Padding.MEDIUM);
scroller.setScrollDirection(Scroller.ScrollDirection.VERTICAL);
add(scroller);
```

**React** — `scroller-basic.tsx`

```tsx
<Scroller className="border-b p-m" scrollDirection="vertical">
  <section aria-labelledby="personal-title">
    <h3 className="text-l" id="personal-title">Personal information</h3>
    <TextField className="w-full" label="First name" />
    <TextField className="w-full" label="Last name" />
    <DatePicker initialPosition="1990-01-01" label="Birthdate" className="w-full" />
  </section>
  <section aria-labelledby="employment-title">
    <h3 className="mt-l text-l" id="employment-title">Employment information</h3>
    <TextField className="w-full" label="Position" />
    <TextArea className="w-full" label="Additional information" />
  </section>
</Scroller>
```

## <a id="scroll-direction"></a>Scroll Direction

Scroller supports four scroll directions: **vertical**, **horizontal**, **both**, and **none**. The default is **both**.

### <a id="vertical"></a>Vertical

When vertical scrolling is enabled, users can scroll down if the content exceeds the container’s height. Horizontal overflow, however, is clipped and inaccessible—so the content’s width should be set to 100%.

### <a id="horizontal"></a>Horizontal

When horizontal scrolling is enabled, users can scroll sideways if the content exceeds the container’s width. However, vertical overflow is clipped and inaccessible—so the content’s height should be set to 100%.

> **Note:** Use horizontal scrolling with caution, as it’s less common and can be harder for users to notice and interact with—especially on non-mobile devices.

#### <a id="desktop"></a>Desktop

Aside from grids, horizontal scrolling is uncommon in desktop or business applications, as it can be unintuitive and cumbersome.

To improve usability, consider using buttons to make horizontal scrolling more noticeable and accessible. For horizontally scrollable lists, it’s good practice to indicate the total number of items and highlight which ones are currently in view.

#### <a id="mobile"></a>Mobile

Horizontal scrolling or swiping is more common on mobile, often used for navigation. It can also help conserve vertical space—for example, when displaying less important content such as shortcuts or images.

**Lit** — `scroller-mobile.ts`

```typescript
<vaadin-scroller scroll-direction="horizontal">
  <vaadin-horizontal-layout class="inline-flex" theme="padding spacing">
    <vaadin-button style="height: 100px;">
      <vaadin-icon icon="vaadin:clipboard-check" slot="prefix"></vaadin-icon>
      Audit
    </vaadin-button>
    <vaadin-button style="height: 100px;">
      <vaadin-icon icon="vaadin:book-dollar" slot="prefix"></vaadin-icon>
      Report
    </vaadin-button>
    <vaadin-button style="height: 100px;">
      <vaadin-icon icon="vaadin:line-chart" slot="prefix"></vaadin-icon>
      Dashboard
    </vaadin-button>
    <vaadin-button style="height: 100px;">
      <vaadin-icon icon="vaadin:invoice" slot="prefix"></vaadin-icon>
      Invoice
    </vaadin-button>
  </vaadin-horizontal-layout>
</vaadin-scroller>
```

**Flow** — `ScrollerMobile.java`

```java
Scroller scroller = new Scroller();
scroller.setScrollDirection(Scroller.ScrollDirection.HORIZONTAL);

Button auditBtn = new Button("Audit");
auditBtn.setIcon(new Icon(VaadinIcon.CLIPBOARD_CHECK));
auditBtn.setHeight("100px");

Button reportBtn = new Button("Report");
reportBtn.setIcon(new Icon(VaadinIcon.BOOK_DOLLAR));
reportBtn.setHeight("100px");

Button dashboardBtn = new Button("Dashboard");
dashboardBtn.setIcon(new Icon(VaadinIcon.LINE_CHART));
dashboardBtn.setHeight("100px");

Button invoiceBtn = new Button("Invoice");
invoiceBtn.setIcon(new Icon(VaadinIcon.INVOICE));
invoiceBtn.setHeight("100px");

HorizontalLayout buttons = new HorizontalLayout(auditBtn, reportBtn,
        dashboardBtn, invoiceBtn);
buttons.addClassName(LumoUtility.Display.INLINE_FLEX);
buttons.setPadding(true);

scroller.setContent(buttons);
add(scroller);
```

**React** — `scroller-mobile.tsx`

```tsx
<Scroller scroll-direction="horizontal">
  <HorizontalLayout className="inline-flex" theme="padding spacing">
    <Button style={{ height: '100px' }}>
      <Icon icon="vaadin:clipboard-check" slot="prefix" />
      Audit
    </Button>
    <Button style={{ height: '100px' }}>
      <Icon icon="vaadin:book-dollar" slot="prefix" />
      Report
    </Button>
    <Button style={{ height: '100px' }}>
      <Icon icon="vaadin:line-chart" slot="prefix" />
      Dashboard
    </Button>
    <Button style={{ height: '100px' }}>
      <Icon icon="vaadin:invoice" slot="prefix" />
      Invoice
    </Button>
  </HorizontalLayout>
</Scroller>
```

### <a id="both"></a>Both

When the scroll direction is set to **Both** (the default), users can scroll both vertically and horizontally if the content overflows in either direction.

This option is ideal for allowing users to pan across large elements, such as images. It can also serve as a fallback for responsive layouts that may overflow in certain situations.

**Lit** — `scroller-both.ts`

```typescript
<vaadin-scroller class="w-full" style="height: 300px">
  <img src="${img}" alt="A reindeer walking on a snowy lake shore at dusk" />
</vaadin-scroller>
```

**Flow** — `ScrollerBoth.java`

```java
Scroller scroller = new Scroller();
scroller.setWidthFull();
scroller.setHeight("300px");

DownloadHandler imageHandler = DownloadHandler.forClassResource(
        getClass(), "/images/reindeer.jpg", "reindeer.jpg");

Image img = new Image(imageHandler,
        "A reindeer walking on a snowy lake shore at dusk");
scroller.setContent(img);

add(scroller);
```

**React** — `scroller-both.tsx`

```tsx
<Scroller style={{ height: '300px', width: '100%' }}>
  <img src={img} alt="A reindeer walking on a snowy lake shore at dusk" />
</Scroller>
```

### <a id="none"></a>None

Use **None** to hide overflowing content in either direction. No scrollbars are provided, and the clipped content is inaccessible. **None** is useful in fixed-size or fixed-layout scenarios where overflow would cause issues.

## <a id="theme-variants"></a>Theme Variants

Scroller has one theme variant: `overflow-indicators`.

This variant adds borders to indicate when content overflows the scroll container. For example, if more content is available by scrolling down, a bottom border appears. If content overflows at the top, a top border is shown, and so on for other directions.

You shouldn’t add padding to the scroller when using this variant, as it prevents the borders from appearing in the correct positions.

**Lit** — `scroller-overflow-indicators.ts`

```typescript
<vaadin-scroller scroll-direction="vertical" theme="overflow-indicators">
  <div class="flex flex-col pb-m px-m">
    <vaadin-text-field label="First name"></vaadin-text-field>
    <vaadin-text-field label="Last name"></vaadin-text-field>
    <vaadin-email-field label="Email"></vaadin-email-field>
    <vaadin-text-field label="Phone number"></vaadin-text-field>
    <vaadin-text-field label="Address"></vaadin-text-field>
    <vaadin-text-field label="City"></vaadin-text-field>
    <vaadin-combo-box label="State"></vaadin-combo-box>
    <vaadin-text-field label="Zip code"></vaadin-text-field>
    <vaadin-combo-box label="Country"></vaadin-combo-box>
    <vaadin-checkbox label="Agree to terms and conditions"></vaadin-checkbox>
  </div>
</vaadin-scroller>
```

**Flow** — `ScrollerOverflowIndicators.java`

```java
TextField firstName = new TextField("First name");
TextField lastName = new TextField("Last name");
EmailField email = new EmailField("Email");
TextField phoneNumber = new TextField("Phone number");
TextField address = new TextField("Address");
TextField city = new TextField("City");
ComboBox<String> state = new ComboBox<>("State");
TextField zipCode = new TextField("Zip code");
ComboBox<String> country = new ComboBox<>("Country");

Div div = new Div(firstName, lastName, email, phoneNumber, address, city, state, zipCode, country);
div.addClassNames(LumoUtility.Display.FLEX, LumoUtility.FlexDirection.COLUMN, LumoUtility.Padding.Bottom.MEDIUM,
        LumoUtility.Padding.Horizontal.MEDIUM);

Scroller scroller = new Scroller(div);
scroller.addThemeVariants(ScrollerVariant.LUMO_OVERFLOW_INDICATORS);
scroller.setScrollDirection(Scroller.ScrollDirection.VERTICAL);
add(scroller);
```

**React** — `scroller-overflow-indicators.tsx`

```tsx
<Scroller scrollDirection="vertical" theme="overflow-indicators">
  <div className="flex flex-col pb-m px-m">
    <TextField className="w-full" label="First name"></TextField>
    <TextField className="w-full" label="Last name"></TextField>
    <TextField className="w-full" label="Email"></TextField>
    <TextField className="w-full" label="Phone number"></TextField>
    <TextField className="w-full" label="Address"></TextField>
    <TextField className="w-full" label="City"></TextField>
    <TextField className="w-full" label="State"></TextField>
    <TextField className="w-full" label="Zip code"></TextField>
    <TextField className="w-full" label="Country"></TextField>
    <Checkbox label="Agree to terms and conditions" />
  </div>
</Scroller>
```

## <a id="related-components"></a>Related Components

| Component                                                                        | Usage recommendations                                          |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [Horizontal Layout](https://vaadin.com/docs/v24/components/horizontal-layout.md) | A layout that aligns components and HTML elements horizontally |
| [Vertical Layout](https://vaadin.com/docs/v24/components/vertical-layout.md)     | A layout that aligns components and HTML elements vertically.  |

`6DC07651-5F23-4ADD-B8CD-E87750453184`