We use essential cookies for the website to function, as well as analytics cookies for analyzing and creating statistics of the website performance. To agree to the use of analytics cookies, click "Accept All". You can manage your preferences at any time by clicking "Cookie Settings" on the footer. More Information.

Cookie Settings
Only Essential Cookies
Accept All
MaterialsConsole

HarmonyOS

输入关键字搜索
HMS Core
AppGallery Connect
HUAWEI HiAI
CTRL+K
Advanced filters
Created with Pixso.
API versionAll
DeviceAll
Atomic service APIsNot filter by this
ReferencesApplication FrameworkArkUIArkTS ComponentsScrolling and SwipingScrollBar

ScrollBar

Phone12+PC/2in113+Tablet12+TV19+Wearable18+
Last updated: 2026-09-04 06:52
Content overview
Expand

The ScrollBar component is designed to be used together with scrollable components such as ArcList, List, Grid, Scroll, and WaterFlow.

NOTE
  • This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
  • If the size of the main axis direction is not set for ScrollBar, the maxSize value in the layout constraints of the parent component is used. If the parent component of the ScrollBar component contains a scrollable component, such as ArcList, List, Grid, Scroll, or WaterFlow, you are advised to set the size in the main axis direction of the ScrollBar; otherwise, the size in the main axis direction of ScrollBar may become infinite.

Child Components

This component can contain a single child component.

APIs

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

ScrollBar(value: ScrollBarOptions)

Creates a scroll bar.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
value ScrollBarOptions Yes Parameters of the ScrollBar component.

Attributes

In addition to the universal attributes, the following attributes are supported.

enableNestedScroll14+

Phone14+PC/2in114+Tablet14+TV19+Wearable18+

enableNestedScroll(enabled: Optional<boolean>)

Sets whether nested scrolling is enabled.

Atomic service API: This API can be used in atomic services since API version 14.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
enabled Optional<boolean> Yes

Whether nested scrolling is enabled. The value true means that nested scrolling is enabled, and false means the opposite.

Default value: false
NOTE

When nested scrolling is enabled, the scroll offset is first passed to the inner scrollable component, which then passes it to the outer parent scrollable component based on the set nested scrolling priority.

Nested scrolling is not supported when the WaterFlow component is in WaterFlowLayoutMode.SLIDING_WINDOW layout mode.

When the nested scrolling mode is set to PARALLEL, both the parent and child components scroll simultaneously. You need to manage the scroll order in the onScrollFrameBegin event according to the desired logic.

scrollBarColor20+

Phone20+PC/2in120+Tablet20+TV20+Wearable20+

scrollBarColor(color: Optional<ColorMetrics>)

Sets the color of the scrollbar slider. This parameter is valid only when the scrollbar does not contain child components.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Expand
Name Type Mandatory Description
color Optional<ColorMetrics> Yes

Scrollbar color.

Default value: ColorMetrics.numeric(0x66182431)

ScrollBarOptions

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Parameters of the ScrollBar component.

NOTE
  • The ScrollBar component defines the behavior style of the scrollable area, and its child nodes define the behavior style of the scrollbar.
  • This component is bound to a scrollable component through scroller, and can be used to scroll the scrollable component only when their directions are the same. The ScrollBar component can be bound to only one scrollable component, and vice versa.
  • Since API version 12, the ScrollBar component displays a default scrollbar style when without child nodes.
  • The visibility of the ScrollBar component is set through BarState. The component automatically adjusts opacity based on the BarState setting to control its visibility. Therefore, setting the opacity attribute for the ScrollBar component does not take effect.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Type Read-Only Optional Description
scroller Scroller No No Scroller, which can be bound to scrollable components for scrolling control.
direction ScrollBarDirection No Yes

Scrollbar direction in which scrollable components scroll.

Default value: ScrollBarDirection.Vertical
state BarState No Yes

Scrollbar state.

Default value: BarState.Auto

ScrollBarDirection

Phone12+PC/2in113+Tablet12+TV19+Wearable18+

Enumerates the scrolling directions.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Expand
Name Value Description
Vertical 0 Vertical scrollbar.
Horizontal 1 Horizontal scrollbar.

Example 1: Implementing a ScrollBar Component with Child Components

This example illustrates the style of a ScrollBar component with child components.

Collapse
Word wrap
Dark theme
Copy code
  1. // xxx.ets
  2. @Entry
  3. @Component
  4. struct ScrollBarExample {
  5.   private scroller: Scroller = new Scroller();
  6.   private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
  7. 

  8.   build() {
  9.     Column() {
  10.       Stack({ alignContent: Alignment.End }) {
  11.         Scroll(this.scroller) {
  12.           Flex({ direction: FlexDirection.Column }) {
  13.             ForEach(this.arr, (item: number) => {
  14.               Row() {
  15.                 Text(item.toString())
  16.                   .width('80%')
  17.                   .height(60)
  18.                   .backgroundColor('#3366CC')
  19.                   .borderRadius(15)
  20.                   .fontSize(16)
  21.                   .textAlign(TextAlign.Center)
  22.                   .margin({ top: 5 })
  23.               }
  24.             }, (item: number) => item.toString())
  25.           }.margin({ right: 15 })
  26.         }
  27.         .width('90%')
  28.         .scrollBar(BarState.Off)
  29.         .scrollable(ScrollDirection.Vertical)
  30. 

  31.         ScrollBar({ scroller: this.scroller, direction: ScrollBarDirection.Vertical, state: BarState.Auto }) {
  32.           Text()
  33.             .width(20)
  34.             .height(100)
  35.             .borderRadius(10)
  36.             .backgroundColor('#C0C0C0')
  37.         }.width(20).backgroundColor('#ededed')
  38.       }
  39.     }
  40.   }
  41. }

Example 2: Implementing a ScrollBar Component Without Child Components

This example illustrates the style of a ScrollBar component without child components. The scrollBarColor attribute is added since API version 20.

Collapse
Word wrap
Dark theme
Copy code
  1. import { ColorMetrics } from '@kit.ArkUI'
  2. 

  3. @Entry
  4. @Component
  5. struct ScrollBarExample {
  6.   private scroller: Scroller = new Scroller();
  7.   private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15];
  8.   @State scrollBarColor: ColorMetrics = ColorMetrics.rgba(24, 35, 48, 0.4);
  9. 

  10.   build() {
  11.     Column() {
  12.       Stack({ alignContent: Alignment.End }) {
  13.         Scroll(this.scroller) {
  14.           Flex({ direction: FlexDirection.Column }) {
  15.             ForEach(this.arr, (item: number) => {
  16.               Row() {
  17.                 Text(item.toString())
  18.                   .width('80%')
  19.                   .height(60)
  20.                   .backgroundColor('#3366CC')
  21.                   .borderRadius(15)
  22.                   .fontSize(16)
  23.                   .textAlign(TextAlign.Center)
  24.                   .margin({ top: 5 })
  25.               }
  26.             }, (item: number) => item.toString())
  27.           }.margin({ right: 15 })
  28.         }
  29.         .width('90%')
  30.         .scrollBar(BarState.Off)
  31.         .scrollable(ScrollDirection.Vertical)
  32. 

  33.         ScrollBar({ scroller: this.scroller, direction: ScrollBarDirection.Vertical, state: BarState.Auto })
  34.           .scrollBarColor(this.scrollBarColor)
  35.       }
  36.     }
  37.   }
  38. }

Example 3: Enabling Nested Scrolling

This example demonstrates how to enable nested scrolling for a ScrollBar component using the enableNestedScroll attribute. This feature is available from API version 20.

Collapse
Word wrap
Dark theme
Copy code
  1. import { ColorMetrics } from '@kit.ArkUI'
  2. 

  3. @Entry
  4. @Component
  5. struct StickyNestedScroll {
  6.   listScroller: Scroller = new Scroller();
  7.   @State array: number[] = [];
  8.   @State scrollBarColor: ColorMetrics = ColorMetrics.rgba(24, 35, 48, 0.4);
  9. 

  10.   @Styles
  11.   listCard() {
  12.     .backgroundColor(Color.White)
  13.     .height(72)
  14.     .width('100%')
  15.     .borderRadius(12)
  16.   }
  17. 

  18.   build() {
  19.     Stack() {
  20.       Scroll() {
  21.         Column() {
  22.           Text('Scroll Area')
  23.             .width('100%')
  24.             .height('40%')
  25.             .backgroundColor('#0080DC')
  26.             .textAlign(TextAlign.Center)
  27.           List({ space: 10, scroller: this.listScroller }) {
  28.             ForEach(this.array, (item: number) => {
  29.               ListItem() {
  30.                 Text('item' + item)
  31.                   .fontSize(16)
  32.               }
  33.               .listCard()
  34.             }, (item: number) => item.toString())
  35.           }
  36.           .scrollBar(BarState.Off)
  37.           .nestedScroll({
  38.             scrollForward: NestedScrollMode.PARENT_FIRST,
  39.             scrollBackward: NestedScrollMode.SELF_FIRST
  40.           })
  41.           .height('100%')
  42.         }
  43.         .width('100%')
  44.       }
  45.       .edgeEffect(EdgeEffect.Spring)
  46.       .backgroundColor('#DCDCDC')
  47.       .scrollBar(BarState.Off)
  48.       .width('100%')
  49.       .height('100%')
  50. 

  51.       ScrollBar({ scroller: this.listScroller })
  52.         .position({ right: 0 })
  53.         .enableNestedScroll(true)
  54.         .scrollBarColor(this.scrollBarColor)
  55.     }
  56.   }
  57. 

  58.   aboutToAppear() {
  59.     for (let i = 0; i < 15; i++) {
  60.       this.array.push(i);
  61.     }
  62.   }
  63. }

LazyDynamicLayout
Refresh
English
©2026 HUAWEI Developers. All rights reserved.
Terms of Use
Statement About HUAWEI Developers and Privacy
Cookies
Cookie Settings
Open-Source Software Notice