ARIA: scrollbar role
A scrollbar
is a graphical object that controls the scrolling of content within a viewing area.
Description
A scrollbar
is a range that controls what part of a viewport's content is currently visible in the viewport's frame; whether the viewport is a full browser size, an iframe, or any element's block formatting context.
What is scroll bar
Many applications provide native scroll bars when the content area is larger than the application window. Scrollbars generally appear on the right or bottom of the viewing area. Native scroll bars appear as thin rectangular track areas the length of the viewport it controls with a piece of UI called a thumb or scroller that can be dragged along a track to move the associated content within the viewport. Some scrollbars have arrows at each end of the track that allow scrolling the viewport a short set distance when activated.
Take this document as an example: if the viewport is the full browser window and the content is taller than the viewport, in most browsers the scroll bar on the right edge of the window represents the overall length of the page and the scroll thumb represents the portion of the page content that is currently in the viewport.
Scroll bars may also appear on viewports that are sub-sections of the full browser window. Continuing with this content as our example, if this content is embedded in an <iframe>
or <object>
, the native vertical scroll bar will be the height of the frame. A scroll bar generally is the length of the viewport, but isn't required to be.
If you aren't currently seeing a scroll bar, it may be because your browser only displays the scroll bar when scrolling or only when an element's content is too big to fit in its block formatting context. Depending on the browser and operating system, scroll bars can be made to be visible even when the content fits in the viewport when no scrolling is necessary or even possible.
ARIA scrollbar
It is always best to use native scroll bars. You can use the CSS overflow
property to ensure the appearance of native scroll bars. A CSS scrollbar specification is being developed. Some browsers allow styling scroll bars via prefixed pseudo-elements.
Because native scroll bar styling has historically been limited, you may come across a scrollbar implemented in JavaScript that you need to support and make fully accessible. For this, you can use the scrollbar
role to inform assistive technologies that a UI control is an interactive scrollbar.
An element with the scrollbar
role is a graphical object that controls the scrolling of content within a viewing area; it is the ARIA role which indicates an element is a scroll bar. The HTML element that is most similar is the range
<input>
type, <input type="range">
.
The scrollbar
element has two required attributes: aria-controls
and aria-valuenow
. The aria-controls
attribute references the id
of the scrollable area it controls. The aria-valuenow
property defines the current value of the scrollbar.
While the aria-valuenow
is always required, the aria-valuemin
and aria-valuemax
properties only need to be set for the scrollbar role when the scrollbar
's minimum value is not 0 or the maximum value is not 100. The value of aria-valuenow
must always be between the minimum and maximum inclusive values, or between 0
and 100
inclusive if the minimum and maximum values default to 0
and 100
respectively. aria-valuenow
communicates how close the viewport is to the bottom of the document. Think of it like a progress bar, where the start of the document is the minimum value and the end of the document is the maximum value.
A scrollbar
represents the current value and range of possible values via the size of the scrollbar and position of the thumb with respect to the visible range of the orientation (horizontal or vertical) it controls. In other words, the scrollbar
length (height or width) represents all the content within a viewport. The aria-valuemin
value represents the beginning of the content and the scrollbar, the aria-valuemax
value represents the end of the content and the end of the scrollbar. The aria-valuenow
represents the content that is currently visible in the viewport and the current position, or value, of the movable thumb. The aria-valuenow
value will generally be exposed as a percentage between aria-valuemin
and aria-valuemax
calculated by assistive technologies.
Note: Assistive technologies generally render the value of aria-valuenow
as a percent of a range between the value of aria-valuemin
and aria-valuemax
, unless aria-valuetext
is set. It is recommended to set the values for aria-valuemin
, aria-valuemax
, and aria-valuenow
in a manner that is appropriate for this calculation.
Like a native scroll bar, users interact with scrollbar
elements directly or indirectly using mouse, touchpad, keyboard, and voice input. scrollbar
role implementations must also accommodate all these interaction methods.
When using a mouse, the user must be able to activate the scrollbar
by clicking the scroll arrows at either end of the scroll bar, if present, clicking an empty portion of the scroll track, as well as clicking and dragging the scroll thumb.
Keyboard scrolling must also be supported. When focus is within the viewport controlled by a scrollbar
, the Up Arrow and Down Arrow (or Left Arrow and Right Arrow for a horizontal scroll bar) should move the scroll bar thumb proportionally. Additionally, the Page Up, Page Down, Space, and Shift + Space keys must move the content and the scroll thumb the height (or width) of the viewport for each key press until the bottom or top (or left or right) of the content is in view.
JavaScript must be used to translate the scrollbar
action into scrolling commands, providing the user with feedback by:
- Visually updating the
scrollbar
element, - Scrolling the viewport's content, and
- Updating the
aria-valuenow
property value.
The default orientation of the scrollbar
role is vertical. Including aria-orientation="vertical"
, in this case, is optional. The orientation represents the orientation of the scrollbar and the scrolling effect on the viewing area controlled by the scrollbar. If the scrolling is left to right or right to left and not top to bottom, include aria-orientation="horizontal"
on the element with the scrollbar
role.
Note: An accessible name is required. If the scrollbar
role is applied to an HTML <input>
element (or <meter>
or <progress>
element), the accessible name can come from the associated <label>
. Otherwise use aria-labelledby
if a visible label is present or aria-label
if a visible label is not present.
All descendants are presentational
There are some types of user interface components that, when represented in a platform accessibility API, can only contain text. Accessibility APIs do not have a way of representing semantic elements contained in a scrollbar
. To deal with this limitation, browsers, automatically apply role presentation
to all descendant elements of any scrollbar
element as it is a role that does not support semantic children.
For example, consider the following scrollbar
element, which contains a heading.
html
<div role="scrollbar"><h3>Title of my scrollbar</h3></div>
Because descendants of scrollbar
are presentational, the following code is equivalent:
html
<div role="scrollbar"><h3 role="presentation">Title of my scrollbar</h3></div>
From the assistive technology user's perspective, the heading does not exist since the previous code snippets are equivalent to the following in the accessibility tree:
html
<div role="scrollbar">Title of my scrollbar</div>
Associated WAI-ARIA roles, states, and properties
aria-controls
(Required)-
Identifies the viewport, via the
id
, whose contents controlled by the scrollbar. aria-valuenow
(Required)-
Set to a decimal value between
0
, oraria-valuemin
if present, andaria-valuemax
indicating the current value of the scrollbar. aria-valuetext
-
Assistive technologies often present the value of
aria-valuenow
as a percentage. If this would not be helpful, use this property to make the scrollbar value more understandable to users. aria-valuemin
-
Set to a decimal value representing the minimum value, and less than
aria-valuemax
. If not present, the default value is0
. aria-valuemax
-
Set to a decimal value representing the maximum value, and greater than
aria-valuemin
. If not present, the default value is100
. aria-labelledby
-
When not using a native form control and therefore not able to associate the scrollbar with a
<label>
, if visible text is available that can provide the required accessible name, set to theid
of an element containing text serving as a label. Otherwise, usearia-label
. aria-label
-
If no
<label>
can be used, and no visible text is present that can be referenced byaria-labelledby
, provides the string value that labels thescrollbar
element providing the required accessible name. aria-orientation
-
By default, the orientation is
vertical
. The property can be included and set tohorizontal
,undefined
(the default for all roles unless otherwise specified), orvertical
.
Keyboard interactions
- Up Arrow
-
The content in the viewport moves up one line with the thumb moving up the scroll bar slider proportionally, until the top of the content and scrollbar are reached.
- Down Arrow
-
The content in the viewport moves down one line with the thumb moving down the scroll bar slider proportionally, until the bottom of the content and scrollbar are reached.
- Left Arrow
-
With horizontal scrolling, the content in the viewport moves left the width of one character with the thumb moving left across the scroll bar slider proportionally, until the left edge of the content abuts the left end of the viewport and the thumb is aligned on the left end of the scrollbar.
- Right Arrow
-
With horizontal scrolling, the content in the viewport moves right the width of one character with the thumb moving right across the scroll bar slider proportionally, until the right edge of the content abuts the right end of the viewport and the thumb is aligned on the right end of the scrollbar.
- Page Up and Shift + Space
-
The content in the viewport moves up the height of one viewport with the thumb moving up the scroll bar slider proportionally, until the top of the content and scrollbar are reached.
- Page Down and Space
-
The content in the viewport moves down the height of one viewport with the thumb moving down the scroll bar slider proportionally, until the bottom of the content and scrollbar are reached.the bottom or top of the content is in view.
Examples
The following is an example of a word likely being too long for a parent container.
html
<span id="pi-label">Pi</div>
<div id="pi">
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
</div>
<div
role="scrollbar"
aria-labelledby="pi-label"
aria-controls="pi"
aria-orientation="horizontal"
aria-valuenow="0"
aria-valuemin="0"
aria-valuemax="100">
<div id="thumb"></div>
</div>
When using the ARIA roles instead of native UI features, CSS must be used to style the scrollbar and thumb and JavaScript must be used to handle all keyboard and pointer events.
CSS could have been used to ensure the overflowing value of PI had a native scrollbar:
html
<h3 id="PI">Pi</h3>
<p class="pi" tabindex="0" aria-labelledby="PI">
3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
</p>
css
.pi {
overflow: auto;
max-width: 100%;
}
The above CSS means a native scroll bar will appear when the user interacts with the paragraph's viewport if the length of the longest word in the paragraph is wider than the paragraphs containing box. The tabindex
attribute was added to allow people using a keyboard to navigate to, and scroll around the overflowed content.
Specifications
Specification |
---|
Accessible Rich Internet Applications (WAI-ARIA) # scrollbar |
See Also
<input type="range">
,- HTML
<progress>
element - HTML
<meter>
element - Other range widgets include:
meter
slider
separator
(if focusable)progressbar
spinbutton
- Document
scroll
event