Documentation

Documentation versions (currently viewingVaadin 23)
New Acceleration Kits: Observability Kit, SSO Kit, and Swing Kit. Read the blog post.

Scroller

Scroller is a component container for creating scrollable areas in the UI.

Open in a
new tab
<vaadin-scroller
  scroll-direction="vertical"
  style="border-bottom: 1px solid var(--lumo-contrast-20pct); padding: var(--lumo-space-m);"
>
  <section aria-labelledby="personal-title">
    <h3 id="personal-title">Personal information</h3>
    <vaadin-text-field style="width: 100%;" label="First name"></vaadin-text-field>
    <vaadin-text-field style="width: 100%;" label="Last name"></vaadin-text-field>
    <vaadin-date-picker
      initial-position="1990-01-01"
      label="Birthdate"
      style="width: 100%;"
    ></vaadin-date-picker>
  </section>
  <section aria-labelledby="employment-title">
    <h3 id="employment-title">Employment information</h3>
    <vaadin-text-field style="width: 100%;" label="Position"></vaadin-text-field>
    <vaadin-text-area
      style="width: 100%;"
      label="Additional information"
    ></vaadin-text-area>
  </section>
</vaadin-scroller>

Scroll Direction

Scroller has four different scroll directions: vertical, horizontal, both, and none. Scroller’s default scroll direction is both.

Vertical

When the scroll position is vertical, the user can scroll vertically if the content overflows the container vertically. Content that overflows horizontally is clipped and inaccessible, so the width of the content should be 100%.

Horizontal

When the scroll position is horizontal, the user can scroll horizontally if the content overflows the container horizontally. Content that overflows vertically is clipped and inaccessible, so the height of the content should be 100%.

Note

Use horizontal scrolling with caution, as it’s much less common and may be difficult for users to recognize and use, in particular on non-mobile devices.

Desktop

Excluding Grids, horizontal scrolling isn’t commonly used in desktop and/or business applications, as it can be non-obvious and cumbersome to use.

It’s recommended to use Buttons to help users notice and navigate horizontally scrollable sections. For horizontally scrollable lists, it’s considered good practice to display the number of items there are in the list, and which items the user is currently viewing.

Mobile

Scrolling horizontally or swiping is more common on mobile, for example for navigation purposes. It can also be used to conserve vertical space, for example in situations where the user is exploring less-important information, such as shortcuts or images.

Open in a
new tab
<vaadin-scroller scroll-direction="horizontal">
  <vaadin-horizontal-layout style="display: 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>

Both

When the scroll position is Both (default), the user can scroll vertically and horizontally if the content overflows in both directions.

This scroll direction is best suited to allowing the user to pan around large elements, such as images. It can also be used as a fallback for a responsive layout that can’t be guaranteed not to overflow in some situations.

Open in a
new tab
<vaadin-scroller style="height: 300px; width: 100%;">
  <img src="${img}" alt="A reindeer walking on a snowy lake shore at dusk" />
</vaadin-scroller>

None

Use None to hide content that overflows in either direction. No scrollbars are available to the user to access the clipped content. None can be used in fixed-size/fixed-layout situations, where overflow would cause issues.

Component Usage recommendations

Basic Layouts

Layouts that align components and HTML elements horizontally and vertically.

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