1# Badge
2
3The **\<Badge>** component is a container that can be attached to another component for tagging.
4
5>  **NOTE**
6>
7> This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
8
9
10## Child Components
11
12This component supports only one child component.
13
14>  **NOTE**
15>
16>  Supported types of child components: built-in components and custom components, with support for ([if/else](../../../quick-start/arkts-rendering-control-ifelse.md), [ForEach](../../../quick-start/arkts-rendering-control-foreach.md), and [LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)) rendering control.
17
18
19## APIs
20
21### Badge
22
23Badge(value: BadgeParamWithNumber)
24
25Creates a badge.
26
27**Widget capability**: This API can be used in ArkTS widgets since API version 9.
28
29**Atomic service API**: This API can be used in atomic services since API version 11.
30
31**System capability**: SystemCapability.ArkUI.ArkUI.Full
32
33**Parameters**
34
35| Name| Type| Mandatory| Description|
36| -------- | -------- | -------- | -------- |
37| value |  [BadgeParamWithNumber](#badgeparamwithnumber)| Yes| Parameter of the numbered badge.|
38
39### Badge
40
41Badge(value: BadgeParamWithString)
42
43Creates a badge based on the given string.
44
45**Widget capability**: This API can be used in ArkTS widgets since API version 9.
46
47**Atomic service API**: This API can be used in atomic services since API version 11.
48
49**System capability**: SystemCapability.ArkUI.ArkUI.Full
50
51This component supports the scaling effect for visibility transition since API version 12.
52
53**Parameters**
54
55| Name| Type                                             | Mandatory| Description            |
56| ------ | ----------------------------------------------------- | ---- | -------------------- |
57| value  | [BadgeParamWithString](#badgeparamwithstring) | Yes  | Parameter of the string-type badge.|
58
59## BadgeParam
60
61Provides basic parameters for creating a **\<Badge>** component.
62
63**Widget capability**: This API can be used in ArkTS widgets since API version 9.
64
65**Atomic service API**: This API can be used in atomic services since API version 11.
66
67**System capability**: SystemCapability.ArkUI.ArkUI.Full
68
69| Name| Type| Mandatory| Description|
70| -------- | -------- | -------- | -------- |
71| position | [BadgePosition](#badgeposition)\|[Position<sup>10+</sup>](ts-types.md#position) | No| Position to display the badge relative to the parent component.<br>Default value: **BadgePosition.RightTop**<br>**NOTE**<br> This parameter cannot be set in percentage. If it is set to an invalid value, the default value **(0,0)** will be used.|
72| style | [BadgeStyle](#badgestyle) | Yes| Style of the badge, including the font color, font size, badge color, and badge size.|
73
74
75## BadgeParamWithNumber
76
77Inherits from [BadgeParam](#badgeparam) and has all attributes of **BadgeParam**.
78
79**Widget capability**: This API can be used in ArkTS widgets since API version 9.
80
81**Atomic service API**: This API can be used in atomic services since API version 11.
82
83**System capability**: SystemCapability.ArkUI.ArkUI.Full
84
85| Name| Type| Mandatory| Description|
86| -------- | -------- | -------- | -------- |
87| count | number | Yes| Number of notifications.<br>**NOTE**<br>If the value is less than or equal to 0, no badge is displayed.<br>Value range: [-2147483648, 2147483647]<br>If the value is out of the range, 4294967296 is added or subtracted so that the value is within the range. If the value is not an integer, it is rounded off to the nearest integer. For example, 5.5 is rounded off to 5.|
88| maxCount | number | No| Maximum number of notifications. When the maximum number is reached, only **maxCount+** is displayed.<br>Default value: **99**<br>Value range: [-2147483648, 2147483647]<br>If the value is out of the range, 4294967296 is added or subtracted so that the value is within the range. If the value is not an integer, it is rounded off to the nearest integer. For example, 5.5 is rounded off to 5.|
89
90## BadgeParamWithString
91
92Inherits from [BadgeParam](#badgeparam) and has all attributes of **BadgeParam**.
93
94**Widget capability**: This API can be used in ArkTS widgets since API version 9.
95
96**Atomic service API**: This API can be used in atomic services since API version 11.
97
98**System capability**: SystemCapability.ArkUI.ArkUI.Full
99
100| Name| Type| Mandatory| Description|
101| -------- | -------- | -------- | -------- |
102| value | string | Yes| Prompt content.|
103
104## BadgePosition
105
106**Widget capability**: This API can be used in ArkTS widgets since API version 9.
107
108**Atomic service API**: This API can be used in atomic services since API version 11.
109
110**System capability**: SystemCapability.ArkUI.ArkUI.Full
111
112| Name| Value| Description|
113| -------- | -------- |-------- |
114| RightTop | 0 | The badge is displayed in the upper right corner of the parent component.|
115| Right | 1 | The badge is vertically centered on the right of the parent component.|
116| Left | 2 | The badge is vertically centered on the left of the parent component.|
117
118## BadgeStyle
119
120**Widget capability**: This API can be used in ArkTS widgets since API version 9.
121
122**Atomic service API**: This API can be used in atomic services since API version 11.
123
124**System capability**: SystemCapability.ArkUI.ArkUI.Full
125
126| Name                     | Type                                                        | Mandatory| Description                                                        |
127| ------------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
128| color                     | [ResourceColor](ts-types.md#resourcecolor)                   | No  | Font color.<br>Default value: **Color.White**                          |
129| fontSize                  | number \| string                                   | No  | Font size.<br>Default value: **10**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.|
130| badgeSize                 | number \| string                                   | No  | Badge size.<br>Default value: **16**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage. If it is set to an invalid value, the default value is used.|
131| badgeColor                | [ResourceColor](ts-types.md#resourcecolor)                   | No  | Badge color.<br>Default value: **Color.Red**                         |
132| fontWeight<sup>10+</sup>  | number \|[FontWeight](ts-appendix-enums.md#fontweight) \| string | No  | Font weight of the text.<br>Default value: **FontWeight.Normal**<br>**NOTE**<br>This parameter cannot be set in percentage.|
133| borderColor<sup>10+</sup> | [ResourceColor](ts-types.md#resourcecolor)                   | No  | Border color of the background.<br>Default value: **Color.Red**                         |
134| borderWidth<sup>10+</sup> | [Length](ts-types.md#length)                                 | No  | Border width of the background.<br>Default value: **1**<br>Unit: vp<br>**NOTE**<br>This parameter cannot be set in percentage.|
135
136## Attributes
137
138The [universal attributes](ts-universal-attributes-size.md) are supported.
139
140## Events
141
142The [universal events](ts-universal-events-click.md) are supported.
143
144## Example
145
146### Example 1
147
148```ts
149// xxx.ets
150@Entry
151@Component
152struct BadgeExample {
153  @Builder tabBuilder(index: number) {
154    Column() {
155      if (index === 2) {
156        Badge({
157          value: '',
158          style: { badgeSize: 6, badgeColor: '#FA2A2D' }
159        }) {
160          Image('/common/public_icon_off.svg')
161            .width(24)
162            .height(24)
163        }
164        .width(24)
165        .height(24)
166        .margin({ bottom: 4 })
167      } else {
168        Image('/common/public_icon_off.svg')
169          .width(24)
170          .height(24)
171          .margin({ bottom: 4 })
172      }
173      Text('Tab')
174        .fontColor('#182431')
175        .fontSize(10)
176        .fontWeight(500)
177        .lineHeight(14)
178    }.width('100%').height('100%').justifyContent(FlexAlign.Center)
179  }
180
181  @Builder itemBuilder(value: string) {
182    Row() {
183      Image('common/public_icon.svg').width(32).height(32).opacity(0.6)
184      Text(value)
185        .width(177)
186        .height(21)
187        .margin({ left: 15, right: 76 })
188        .textAlign(TextAlign.Start)
189        .fontColor('#182431')
190        .fontWeight(500)
191        .fontSize(16)
192        .opacity(0.9)
193      Image('common/public_icon_arrow_right.svg').width(12).height(24).opacity(0.6)
194    }.width('100%').padding({ left: 12, right: 12 }).height(56)
195  }
196
197  build() {
198    Column() {
199      Text('dotsBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24)
200      Tabs() {
201        TabContent()
202          .tabBar(this.tabBuilder(0))
203        TabContent()
204          .tabBar(this.tabBuilder(1))
205        TabContent()
206          .tabBar(this.tabBuilder(2))
207        TabContent()
208          .tabBar(this.tabBuilder(3))
209      }
210      .width(360)
211      .height(56)
212      .backgroundColor('#F1F3F5')
213
214      Column() {
215        Text('stringBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24)
216        List({ space: 12 }) {
217          ListItem() {
218            Text('list1').fontSize(14).fontColor('#182431').margin({ left: 12 })
219          }
220          .width('100%')
221          .height(56)
222          .backgroundColor('#FFFFFF')
223          .borderRadius(24)
224          .align(Alignment.Start)
225
226          ListItem() {
227            Badge({
228              value: 'New',
229              position: BadgePosition.Right,
230              style: { badgeSize: 16, badgeColor: '#FA2A2D' }
231            }) {
232              Text('list2').width(27).height(19).fontSize(14).fontColor('#182431')
233            }.width(49.5).height(19)
234            .margin({ left: 12 })
235          }
236          .width('100%')
237          .height(56)
238          .backgroundColor('#FFFFFF')
239          .borderRadius(24)
240          .align(Alignment.Start)
241        }.width(336)
242
243        Text('numberBadge').fontSize(18).fontColor('#182431').fontWeight(500).margin(24)
244        List() {
245          ListItem() {
246            this.itemBuilder('list1')
247          }
248
249          ListItem() {
250            Row() {
251              Image('common/public_icon.svg').width(32).height(32).opacity(0.6)
252              Badge({
253                count: 1,
254                position: BadgePosition.Right,
255                style: { badgeSize: 16, badgeColor: '#FA2A2D' }
256              }) {
257                Text('list2')
258                  .width(177)
259                  .height(21)
260                  .textAlign(TextAlign.Start)
261                  .fontColor('#182431')
262                  .fontWeight(500)
263                  .fontSize(16)
264                  .opacity(0.9)
265              }.width(240).height(21).margin({ left: 15, right: 11 })
266
267              Image('common/public_icon_arrow_right.svg').width(12).height(24).opacity(0.6)
268            }.width('100%').padding({ left: 12, right: 12 }).height(56)
269          }
270
271          ListItem() {
272            this.itemBuilder('list3')
273          }
274
275          ListItem() {
276            this.itemBuilder('list4')
277          }
278        }
279        .width(336)
280        .height(232)
281        .backgroundColor('#FFFFFF')
282        .borderRadius(24)
283        .padding({ top: 4, bottom: 4 })
284        .divider({ strokeWidth: 0.5, color: 'rgba(0,0,0,0.1)', startMargin: 60, endMargin: 12 })
285      }.width('100%').backgroundColor('#F1F3F5').padding({ bottom: 12 })
286    }.width('100%')
287  }
288}
289```
290
291![badge](figures/badge.png)
292
293### Example 2
294
295```ts
296// This example implements scaling when the badge visibility changes.
297@Entry
298@Component
299struct Index {
300  @State badgeCount: number = 1
301
302  build() {
303    Column({ space: 40 }) {
304      Badge({
305        count: this.badgeCount,
306        style: {},
307        position: BadgePosition.RightTop,
308      }) {
309        Image($r("app.media.icon"))
310        .width(50)
311        .height(50)
312      }
313      .width(55)
314      Button('count 0').onClick(() => {
315        this.badgeCount = 0
316      })
317      Button('count 1').onClick(() => {
318        this.badgeCount = 1
319      })
320    }
321    .margin({top: 20})
322  }
323}
324```
325
326![badgeScale](figures/badgeScale.gif)
327