1# ScrollBar
2
3The **ScrollBar** is used together with scrollable components, such as **List**, **Grid**, and **Scroll**.
4
5>  **NOTE**
6>
7>  This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version.
8
9
10## Child Components
11
12This component can contain a single child component.
13
14
15## APIs
16
17ScrollBar(value: ScrollBarOptions)
18
19**Atomic service API**: This API can be used in atomic services since API version 11.
20
21**System capability**: SystemCapability.ArkUI.ArkUI.Full
22
23**Parameters**
24
25| Name| Type| Mandatory| Description|
26| -------- | -------- | -------- | -------- |
27| value |  [ScrollBarOptions](#scrollbaroptions)| Yes| Scrollbar settings.|
28
29## Properties
30
31In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
32
33## enableNestedScroll<sup>14+</sup>
34
35enableNestedScroll(value: boolean)
36
37Sets whether nested scrolling is enabled.
38
39**Atomic service API**: This API can be used in atomic services since API version 14.
40
41**System capability**: SystemCapability.ArkUI.ArkUI.Full
42
43**Parameters**
44
45| Name| Type   | Mandatory| Description                                 |
46| ------ | ------- | ---- | ------------------------------------- |
47| value  | boolean | Yes  | Whether nested scrolling is enabled. The value **true** means that nested scrolling is enabled, and **false** means the opposite.<br>Default value: **false**|
48
49>  **NOTE**
50>
51> 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.
52>
53> Nested scrolling is not supported when the **WaterFlow** component is in **SLIDING_WINDOW** layout mode.
54>
55> 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.
56
57## ScrollBarOptions
58
59**Atomic service API**: This API can be used in atomic services since API version 11.
60
61**System capability**: SystemCapability.ArkUI.ArkUI.Full
62
63| Name| Type| Mandatory| Description|
64| -------- | -------- | -------- | -------- |
65| scroller | [Scroller](ts-container-scroll.md#scroller) | Yes| Scroller, which can be bound to scrollable components.|
66| direction | [ScrollBarDirection](#scrollbardirection) | No| Scrollbar direction in which scrollable components scroll.<br>Default value: **ScrollBarDirection.Vertical**|
67| state | [BarState](ts-appendix-enums.md#barstate) | No| Scrollbar state.<br>Default value: **BarState.Auto**|
68
69>  **NOTE**
70>
71> The **ScrollBar** component defines the behavior style of the scrollable area, and its subnodes define the behavior style of the scrollbar.
72>
73> 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.
74>
75> Since API version 12, the **ScrollBar** component displays a default scrollbar style when without child nodes.
76
77## ScrollBarDirection
78
79**Atomic service API**: This API can be used in atomic services since API version 11.
80
81**System capability**: SystemCapability.ArkUI.ArkUI.Full
82
83| Name| Description|
84| -------- | -------- |
85| Vertical | Vertical scrollbar.|
86| Horizontal | Horizontal scrollbar.|
87
88
89## Example 1: Implementing a ScrollBar Component with Child Components
90
91This example illustrates the style of a **ScrollBar** component with child components.
92
93```ts
94// xxx.ets
95@Entry
96@Component
97struct ScrollBarExample {
98  private scroller: Scroller = new Scroller()
99  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
100
101  build() {
102    Column() {
103      Stack({ alignContent: Alignment.End }) {
104        Scroll(this.scroller) {
105          Flex({ direction: FlexDirection.Column }) {
106            ForEach(this.arr, (item: number) => {
107              Row() {
108                Text(item.toString())
109                  .width('80%')
110                  .height(60)
111                  .backgroundColor('#3366CC')
112                  .borderRadius(15)
113                  .fontSize(16)
114                  .textAlign(TextAlign.Center)
115                  .margin({ top: 5 })
116              }
117            }, (item:number) => item.toString())
118          }.margin({ right: 15 })
119        }
120        .width('90%')
121        .scrollBar(BarState.Off)
122        .scrollable(ScrollDirection.Vertical)
123        ScrollBar({ scroller: this.scroller, direction: ScrollBarDirection.Vertical,state: BarState.Auto }) {
124          Text()
125            .width(20)
126            .height(100)
127            .borderRadius(10)
128            .backgroundColor('#C0C0C0')
129        }.width(20).backgroundColor('#ededed')
130      }
131    }
132  }
133}
134```
135
136
137![en-us_image_0000001232775585](figures/en-us_image_0000001232775585.gif)
138
139## Example 2: Implementing a ScrollBar Component Without Child Components
140
141This example illustrates the style of a **ScrollBar** component without child components.
142
143```ts
144@Entry
145@Component
146struct ScrollBarExample {
147  private scroller: Scroller = new Scroller()
148  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]
149
150  build() {
151    Column() {
152      Stack({ alignContent: Alignment.End }) {
153        Scroll(this.scroller) {
154          Flex({ direction: FlexDirection.Column }) {
155            ForEach(this.arr, (item: number) => {
156              Row() {
157                Text(item.toString())
158                  .width('80%')
159                  .height(60)
160                  .backgroundColor('#3366CC')
161                  .borderRadius(15)
162                  .fontSize(16)
163                  .textAlign(TextAlign.Center)
164                  .margin({ top: 5 })
165              }
166            }, (item:number) => item.toString())
167          }.margin({ right: 15 })
168        }
169        .width('90%')
170        .scrollBar(BarState.Off)
171        .scrollable(ScrollDirection.Vertical)
172        ScrollBar({ scroller: this.scroller, direction: ScrollBarDirection.Vertical,state: BarState.Auto })
173      }
174    }
175  }
176}
177```
178
179
180![en-us_image_scrollbar](figures/en-us_image_scrollbar.gif)
181
182## Example 3: Enabling Nested Scrolling
183
184This example demonstrates how to enable nested scrolling for a **ScrollBar** component using the **enableNestedScroll** attribute.
185```ts
186@Entry
187@Component
188struct StickyNestedScroll {
189  listScroller: Scroller = new Scroller();
190  @State array: number[] = []
191
192  @Styles
193  listCard() {
194    .backgroundColor(Color.White)
195    .height(72)
196    .width("100%")
197    .borderRadius(12)
198  }
199
200  build() {
201    Stack() {
202      Scroll() {
203        Column() {
204          Text('Scroll Area')
205            .width("100%")
206            .height("40%")
207            .backgroundColor('#0080DC')
208            .textAlign(TextAlign.Center)
209          List({ space: 10, scroller: this.listScroller }) {
210            ForEach(this.array, (item: number) => {
211              ListItem() {
212                Text('item' + item)
213                  .fontSize(16)
214              }
215              .listCard()
216            }, (item: string) => item)
217          }
218          .scrollBar(BarState.Off)
219          .nestedScroll({
220            scrollForward: NestedScrollMode.PARENT_FIRST,
221            scrollBackward: NestedScrollMode.SELF_FIRST
222          })
223          .height("100%")
224        }
225        .width("100%")
226      }
227      .edgeEffect(EdgeEffect.Spring)
228      .backgroundColor('#DCDCDC')
229      .scrollBar(BarState.Off)
230      .width('100%')
231      .height('100%')
232      ScrollBar({ scroller: this.listScroller})
233        .position({right:0})
234        .enableNestedScroll(true)
235    }
236  }
237
238  aboutToAppear() {
239    for (let i = 0; i < 15; i++) {
240      this.array.push(i)
241    }
242  }
243}
244```
245![EnableNestedScroll](figures/EnableNestedScroll.gif)
246