Badge Component

Introduction

The Badge Component is a compact, theme-aware status pill used in grids, planner cards, collection items, and dashboard widgets. It supports semantic variants in light and dark mode; the leading dot is now opt-in.

YAML Structure

The Badge Component is defined in YAML as follows:

component: badge
props:
  label: string        # template-parsed badge text
  colorKey: string     # optional template-parsed lookup key; defaults to normalized label
  color: string        # optional org-defined hex color
  variant: success     # danger | warning | info | success | primary | neutral
  size: sm             # xs | sm | md
  appearance: soft     # soft | outline | solid | ghost
  uppercase: false
  dot: false
  icon: mdi:alert-outline
  maxWidth: 180
  onClick: []          # optional; array of actions to dispatch on click
  options:
    colors:
      default:
        label: string  # text color
        bgcolor: string
        dot: string

Attribute Description

Attribute	Type	Description	Required
label	string	Template-parsed text to display in the badge. Store values, component variables, and form values are available to the template.	Yes
colorKey	string	Optional template-parsed key used to look up options.colors; if omitted, the lowercased label is used. Store values, component variables, and form values are available.	No
onClick	action[]	Actions to dispatch when the badge is clicked. When defined, the badge becomes interactive (pointer cursor). When omitted, the badge is non-interactive.	No
color	string	Template-parsed org color (normally hex); ignored when variant is explicit.	No
variant	string	Semantic color: danger, warning, info, success, primary, or neutral.	No
size	string	xs, sm (default), or md.	No
appearance	string	soft (default), outline, solid, or ghost.	No
uppercase	boolean	Uppercase the label. Defaults to false.	No
dot	boolean	Show the leading dot. Defaults to false.	No
icon	string	Optional icon name.	No
maxWidth	number/string	Clip long labels with an ellipsis.	No
options.colors	object	Optional map keyed by label/colorKey. Values may be semantic variants, hex colors, palette paths, token objects, or legacy triples.	No

Color Options

Color resolution is: explicit variant, label entry, colorKey entry, a key that itself names a variant, options.colors.default, then neutral. Labels are checked before colorKey, keys are case-insensitive, and spaces/hyphens are normalized. Existing {label,bgcolor,dot} maps remain supported.

When a reusable YAML component defines a base options.colors map and its call site supplies overrides, the web renderer merges the color map by key. The call site can therefore replace one status color without discarding the component's remaining colors or default entry. Other option values continue to use normal call-site override behavior.

Examples

Basic Badge

component: badge
props:
  label: "New"

Pill Badge with Custom Colors

Semantic forms are preferred for new modules:

- component: badge
  props: { label: Delivered, variant: success }
- component: badge
  props: { label: 'Order 4', variant: primary, appearance: outline }
- component: badge
  props: { label: 'No route', variant: warning, appearance: outline, icon: 'mdi:alert-outline' }

component: badge
props:
  label: "Urgent"
  colorKey: urgent
  options:
    colors:
      urgent: { label: "#fff", bgcolor: "#d32f2f", dot: "#fff" }
      default: { label: "#333", bgcolor: "#eee", dot: "#999" }

Status Badge

component: badge
props:
  label: "{{ shipmentStatus }}"
  colorKey: "{{ shipmentStatus }}"
  options:
    colors:
      Delivered: { label: "#1b5e20", bgcolor: "#e8f5e9", dot: "#4caf50" }
      default: { label: "#5f370e", bgcolor: "#fff8e1", dot: "#ff9800" }

Clickable Badge Opening a Dialog

component: badge
props:
  label: "{{ shipmentStatus }}"
  colorKey: "{{ shipmentStatus }}"
  onClick:
    - dialog:
        name: "shipmentStatusHistory"
        props:
          shipmentId: "{{ shipmentId }}"
  options:
    colors:
      Delivered: { label: "#1b5e20", bgcolor: "#e8f5e9", dot: "#4caf50" }
      default: { label: "#5f370e", bgcolor: "#fff8e1", dot: "#ff9800" }

When onClick is defined the badge receives a pointer cursor and stops click event propagation so it can be safely embedded inside other clickable elements (e.g. a card or table row).

Best Practices

1. Keep badge text concise: Use short, clear text that can be quickly read and understood.
2. Use consistent colors: Establish a color scheme for different types of badges and stick to it throughout your application.
3. Ensure contrast: Make sure the text color contrasts well with the background color for readability.
4. Use badges sparingly: Overuse of badges can clutter the interface and reduce their impact.
5. Consider accessibility: Ensure that the information conveyed by badges is also available to screen readers.