Badge Component

Introduction

The Badge Component is a versatile UI element in the CXTMS system used to display short, important pieces of information. It's commonly used to highlight status, counts, or labels within the interface.

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
  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
options.colors	object	Color map keyed by colorKey/label, with a default fallback. Each value has label, bgcolor, and dot colors.	Yes

Color Options

Badge colors come from options.colors. Each color entry should define:

• label: text color
• bgcolor: chip background color
• dot: leading dot color

Include a default entry so unknown statuses still render predictably.

Examples

Basic Badge

component: badge
props:
  label: "New"

Pill Badge with Custom Colors

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.