Skip to main content

​
Overview

The Scrollbar class creates a control that allows range selection, commonly used for zooming chart axes or scrolling through large datasets. It features draggable grips and a thumb for intuitive interaction.

​
Constructor

Scrollbar.new(root, settings)
​
root
Root
required
The root element of the chart
​
settings
IScrollbarSettings
Configuration settings for the scrollbar

​
Settings

​
Orientation

​
orientation
'horizontal' | 'vertical'
required
Orientation of the scrollbar.

​
Range Settings

​
start
number
Relative start of the selected range, where 0 is the beginning and 1 is the end.
​
end
number
Relative end of the selected range, where 0 is the beginning and 1 is the end.

​
Animation Settings

​
animationDuration
number
Number of milliseconds to play scroll animations for.
​
animationEasing
(t: Time) => Time
Easing function to use for animations.

​
Properties

​
thumb

​
thumb
RoundedRectangle
The thumb element - a draggable rectangle between the grips used for panning the selection.
scrollbar.thumb.setAll({
  fill: am5.color(0x0000ff),
  fillOpacity: 0.3
});

​
startGrip

​
startGrip
Button
Start grip button for adjusting the start of the range.
scrollbar.startGrip.setAll({
  scale: 1.2
});

​
endGrip

​
endGrip
Button
End grip button for adjusting the end of the range.
scrollbar.endGrip.setAll({
  scale: 1.2
});

​
Methods

​
updateGrips()

Updates the grip positions based on the current start and end values. 
updateGrips(): void
This method is automatically called when start or end changes.

​
Events

​
rangechanged

Fired when the range selection changes. 
scrollbar.events.on("rangechanged", function(ev) {
  console.log("Range:", ev.start, "-", ev.end);
  console.log("Grip:", ev.grip); // "start", "end", or undefined
});
​
start
number
New start position (0-1)
​
end
number
New end position (0-1)
​
grip
'start' | 'end' | undefined
Which grip is being dragged, if any

​
released

Fired when the user releases a grip or thumb after dragging. 
scrollbar.events.on("released", function(ev) {
  console.log("Scrollbar released");
});

​
Examples

​
Basic Horizontal Scrollbar

import { Scrollbar } from "@amcharts/amcharts5";

const scrollbar = Scrollbar.new(root, {
  orientation: "horizontal",
  start: 0.2,
  end: 0.8
});

chart.set("scrollbarX", scrollbar);

​
Vertical Scrollbar

const scrollbar = Scrollbar.new(root, {
  orientation: "vertical"
});

chart.set("scrollbarY", scrollbar);

​
Scrollbar with Custom Styling

const scrollbar = Scrollbar.new(root, {
  orientation: "horizontal"
});

scrollbar.thumb.setAll({
  fill: am5.color(0x3b82f6),
  fillOpacity: 0.5
});

scrollbar.startGrip.setAll({
  scale: 1.5
});

scrollbar.endGrip.setAll({
  scale: 1.5
});

​
Scrollbar with Animation

const scrollbar = Scrollbar.new(root, {
  orientation: "horizontal",
  animationDuration: 500,
  animationEasing: am5.ease.out(am5.ease.cubic)
});

​
Scrollbar with Event Handling

const scrollbar = Scrollbar.new(root, {
  orientation: "horizontal"
});

scrollbar.events.on("rangechanged", function(ev) {
  const start = ev.start;
  const end = ev.end;
  
  // Update axis range
  xAxis.zoom(start, end);
});

scrollbar.events.on("released", function(ev) {
  console.log("User finished adjusting range");
});

​
Scrollbar on XY Chart

const chart = root.container.children.push(
  am5xy.XYChart.new(root, {})
);

const scrollbar = chart.set("scrollbarX",
  am5xy.XYChartScrollbar.new(root, {
    orientation: "horizontal"
  })
);

​
Programmatically Setting Range

const scrollbar = Scrollbar.new(root, {
  orientation: "horizontal"
});

// Set range with animation
scrollbar.setAll({
  start: 0.3,
  end: 0.7,
  animationDuration: 1000
});

// Or set individual values
scrollbar.set("start", 0.4);
scrollbar.set("end", 0.6);

​
Custom Background

const scrollbar = Scrollbar.new(root, {
  orientation: "horizontal",
  background: am5.RoundedRectangle.new(root, {
    fill: am5.color(0xf0f0f0),
    fillOpacity: 0.5,
    cornerRadiusTL: 5,
    cornerRadiusTR: 5,
    cornerRadiusBL: 5,
    cornerRadiusBR: 5
  })
});

​
Interaction Modes

The scrollbar supports three interaction modes:

​
1. Grip Dragging

Drag the start or end grip to adjust one side of the range while keeping the other fixed.

​
2. Thumb Dragging

Drag the thumb (area between grips) to pan the entire range without changing its size.

​
3. Background Clicking

Click on the background to center the thumb at that position, maintaining the current range size.

​
4. Double-Click Reset

Double-click the thumb to reset the range to full (0-1).

​
Accessibility

The scrollbar grips include ARIA attributes:
  • ariaLabel - Descriptive label (“From X” / “To Y”)
  • ariaValueNow - Current value as percentage
  • ariaValueText - Text representation of value
  • ariaValueMin - Minimum value (“0”)
  • ariaValueMax - Maximum value (“100”)
These are automatically updated as the scrollbar is manipulated.

​
Theme Tags

The scrollbar automatically receives theme tags based on its orientation:
  • "scrollbar"
  • "horizontal" or "vertical"
Child elements receive additional tags:
  • "main", "background" - Background
  • "thumb", orientation - Thumb
  • "resize", "button", orientation - Grips
  • "icon" - Grip icons
const myTheme = am5.Theme.new(root);

myTheme.rule("Scrollbar", ["horizontal"]).setAll({
  height: 20
});

myTheme.rule("RoundedRectangle", ["scrollbar", "thumb"]).setAll({
  fillOpacity: 0.5
});

Build docs developers (and LLMs) love

Get started for freeTalk to us