Skip to main content

Badge (ALPHA)

Alpha feature: invite only

Responsive Widgets are in alpha and available by invitation only on Business and Enterprise plans. Behavior and properties may change. To request access, open a support ticket and name the feature Responsive Widgets (ALPHA).

The Badge widget shows a small status marker. It has three modes: a short text such as New, a number such as an unread count, or a plain dot. Add an onClick action to make the badge clickable.

Widget type: WDS_BADGE_WIDGET

Badge widget in a Responsive app
Badge widget

Content properties​

These properties appear in the Content tab of the property pane.

Basic​

Mode string​

Sets what the badge shows. Options:

  • Text (default): a short text.
  • Count: a number, capped by Max.
  • Dot: a small dot with no text.

You set this property in the property pane only. You cannot bind it to data. The other properties in this section change based on the mode.

Text string​

Sets the badge text. Default: New.

This property shows only when Mode is Text.

Count number​

Sets the number the badge shows. Default: 0. You can bind data to it, for example {{GetMessages.data.length}}.

The widget cleans up the value before it shows it:

  • A value that is not a number shows as 0.
  • A negative value shows as 0.
  • A decimal value is rounded down.

This property shows only when Mode is Count.

Max number​

Sets the highest count the badge shows in full. A larger count shows as the max value plus a + sign. For example, with Max set to 99, a count of 120 shows as 99+. Default: 99. The value must be a whole number of 1 or more.

This property shows only when Mode is Count.

Accessible label string​

Sets the name that screen readers announce for the badge, for example Unread notifications. In Count mode, screen readers hear the label and the count, for example "Unread notifications: 5."

This property is required in Count and Dot modes, because the badge has no readable text of its own. The property pane shows an error if it is empty.

This property shows only when Mode is Count or Dot.

General​

Visible boolean​

Controls whether the widget is visible. Default: on.

Animate loading boolean​

Controls the loading animation of the widget. Default: on.

Style properties​

These properties appear in the Style tab of the property pane.

General​

Variant string​

Sets the semantic color of the badge. Options: Accent, Neutral (default), Positive, Negative, Warning.

Values for code: accent, neutral, positive, negative, warning.

Custom styling​

These settings are in the Custom styling section, at the end of the Style tab. An empty setting uses the theme value. For theme colors, dark mode, and the rules for custom CSS, see Custom styling.

Accent color string​

Builds the hover, pressed, focus, and text colors of this widget from one color, in light and dark mode. Lists and menus that the widget opens use them too. Empty means the accent of the nearest container that sets one, or the theme accent. This setting shows only while Variant is Accent.

Custom CSS string​

Adds plain CSS to this widget. Rules apply only inside the widget, and & is the box around the widget, its label included, not the part inside it. To style an inner part, use its element selector, for example button or input. You cannot bind this property.

Reference properties​

Reference properties let you read the widget's state in bindings and code, for example {{Badge1.isVisible}}. You cannot set them directly.

isVisible boolean​

Shows whether the widget is visible.

Example:

{{Badge1.isVisible}}

mode string​

The badge mode: text, count, or dot.

Example:

{{Badge1.mode}}

text string​

The badge text in Text mode.

Example:

{{Badge1.text}}

count number​

The count value in Count mode.

Example:

{{Badge1.count}}

max number​

The highest count the badge shows in full.

Example:

{{Badge1.max}}

variant string​

The semantic color of the badge.

Example:

{{Badge1.variant}}

accessibleLabel string​

The name that screen readers announce for the badge.

Example:

{{Badge1.accessibleLabel}}

Methods​

Methods let you change the widget's properties from code, for example in a JS Object.

setVisibility (param: boolean): Promise​

Shows or hides the widget.

Example:

Badge1.setVisibility(false)

setText (param: string): Promise​

Sets the badge text. The text shows only in Text mode.

Example:

Badge1.setText("Beta")

setCount (param: number): Promise​

Sets the count. The count shows only in Count mode.

Example:

Badge1.setCount(12)

Events​

onClick​

Runs when users click the badge. When you set this event, the badge acts as a button. Users can also press Enter or Space to run it.