badge

Since Jmix 3.1

badge displays a small piece of information, such as a status, a count or a label.

XML Element

badge

Java Class

Badge

Basics

LIVE DEMO

The text attribute sets the label of the badge. Keep it short: one or two words. The success, warning and error theme variants set the color of the badge. Without a variant, the badge uses the accent color of the theme.

<badge id="pendingBadge" text="Pending"/>
<badge id="confirmedBadge" text="Confirmed" themeNames="success"/>
<badge id="warningBadge" text="Warning" themeNames="warning"/>
<badge id="deniedBadge" text="Denied" themeNames="error"/>
Badges with the default and success, warning and error colors

Badges look like buttons, but they are not interactive.

Data-aware badge

LIVE DEMO

A badge can show the value of an entity attribute. Bind it to a data container using the dataContainer and property attributes:

<data>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"
              fetchPlan="_local"/>
</data>
<layout>
    <hbox alignItems="CENTER">
        <badge id="nameBadge" icon="USER" dataContainer="customerDc" property="name"/>
        <badge id="gradeBadge" themeNames="success" dataContainer="customerDc" property="grade"/>
    </hbox>
</layout>

The binding is read-only. The badge shows the attribute value as text and updates it when the value changes. The value is formatted according to its datatype. For example, an enumeration value is shown as its localized caption, and a null value is shown as an empty badge.

If the current user has no permission to view the attribute, the badge is hidden.

Icons

LIVE DEMO

A badge can show an icon before its text. Set the icon using the icon attribute or the nested icon element:

<badge id="pendingBadge" text="Pending" icon="CLOCK"/>
<badge id="confirmedBadge" text="Confirmed" icon="CHECK" themeNames="success"/>
<badge id="warningBadge" text="Warning" icon="WARNING" themeNames="warning"/>
<badge id="deniedBadge" text="Denied" themeNames="error">
    <icon>
        <icon icon="EXCLAMATION_CIRCLE"/>
    </icon>
</badge>
Badges with an icon before the text

The icon-only variant shows only the icon. Set the text anyway. It is hidden on the screen, but screen readers announce it.

<badge id="confirmedIconBadge" text="Confirmed" icon="CHECK" themeNames="success icon-only"/>
<badge id="deniedIconBadge" text="Denied" icon="CLOSE" themeNames="error icon-only"/>

Number

LIVE DEMO

The number attribute shows a number in the badge, for example, the number of unread messages. If the badge has both text and a number, it shows both.

The number-only variant shows only the number. As with icon-only, set the text for screen readers:

<badge id="numberOnlyBadge" text="unread messages" number="5" themeNames="number-only"/>

In the view controller, use the setNumber() method to change the number and setNumber(null) to remove it.

Screen readers read only the content of the badge. A number alone can confuse users, so set a text that says what is counted. If the number changes while the view is open, set ariaRole to status, and screen readers will announce the new value.

Theme Variants

LIVE DEMO

Use the themeNames attribute to apply variants. You can combine several variants, for example, themeNames="success filled". In the view controller, use the addThemeVariants() method with the BadgeVariant enumeration.

Badges with the filled, icon-only, number-only and dot variants
Variant Description Supported By

success, warning, error

Applies a semantic color.

Aura, Lumo

contrast

Applies a neutral high-contrast color.

Lumo

filled

Uses a solid background instead of a tinted one to draw more attention. Can be combined with all other variants.

Aura, Lumo

small

Makes the badge smaller.

Aura, Lumo

icon-only

Shows only the icon. See Icons.

Aura, Lumo

number-only

Shows only the number. See Number.

Aura, Lumo

dot

Shows the badge as a small dot and hides all its content.

Aura, Lumo

Attributes

Common attributes serve the same purpose for all components. The following attributes are specific to badge:

Name Description Default

ariaRole

Sets the ARIA role of the badge, which screen readers use. For example, status makes screen readers announce changes of the badge content. See Number.

—

icon

Sets the icon displayed before the text. See Icons.

—

number

Sets the number displayed in the badge. See Number.

—

themeNames

Applies one or more variants listed in Theme Variants.

—

The following shared attributes are supported by badge:

id - alignSelf - classNames - colspan - css - dataContainer - height - justifySelf - maxHeight - maxWidth - minHeight - minWidth - property - text - visible - whiteSpace - width

Handlers

The following shared handlers are supported by badge:

AttachEvent - DetachEvent

Elements

A badge can include the icon nested element. See Icons.

See Also