Badge

Basic Usage

The badge component supports both positional and keyword argument styles. By default, badges are small pills with a primary color.

<%= rui_badge("New") %>
<%= rui_badge("Success", color: :success) %>
<%= rui_badge(text: "Featured", color: :info) %>

Colors

All semantic and Tailwind colors are supported. The default is primary.

<%= rui_badge(text: "Primary", color: :primary) %>
<%= rui_badge(text: "Success", color: :success) %>
<%= rui_badge(text: "Danger", color: :danger) %>

Sizes

Seven size options from xs to xl2. The default is xs.

<%= rui_badge(text: "XS", size: :xs) %>
<%= rui_badge(text: "SM", size: :sm) %>
<%= rui_badge(text: "Base", size: :base) %>
<%= rui_badge(text: "LG", size: :lg) %>

Shapes

Four border radius options. The default is pill (fully rounded).

<%= rui_badge(text: "Rounded", shape: :rounded) %>

<%= rui_badge(text: "Pill", shape: :pill) %>

<%= rui_badge(text: "Square", shape: :square) %>

<%= rui_badge(text: "5", shape: :circle) %>

Variants

Five distinct visual styles. The default is solid.

<%= rui_badge(text: "Solid", variant: :solid) %>

<%= rui_badge(text: "Outline", variant: :outline) %>

<%= rui_badge(text: "Ghost", variant: :ghost) %>

<%= rui_badge(text: "Soft", variant: :soft) %>

<%= rui_badge(text: "Link", variant: :link) %>

With Icons

Badges support leading and trailing icons. Icons automatically inherit the badge color.

<%= rui_badge(text: "Star", color: :primary) do |badge| %>
  <% badge.with_icon(:star) %>
<% end %>

<%= rui_badge(text: "Next", color: :primary) do |badge| %>
  <% badge.with_icon(:arrow_right, position: :trailing) %>
<% end %>

<%= rui_badge(text: "Custom", color: :blue) do |badge| %>
  <% badge.with_icon(:star, color: :yellow) %>
<% end %>

Interactive Badges

Badges can be dismissible or include close buttons for interactive functionality.

Dismissible Badges

Click anywhere on the badge to dismiss it.

<%= rui_badge(text: "Click to Dismiss", dismissible: true) %>

Close Button

Shows a close icon button for dismissing the badge.

<%= rui_badge(text: "Close Me", close_button: true) %>

Counters

Display numeric counters for notifications, counts, or quantities.

<%= rui_badge(text: "Messages", counter: 5) do |badge| %>
  <% badge.with_icon(:mail) %>
<% end %>

<%= rui_badge(counter: 3, color: :success) %>

Pulsing Animation

Add a pulsing animation to draw attention to important badges.

<%= rui_badge(text: "Live", pulsing: true, color: :danger) do |badge| %>
  <% badge.with_icon(:radio) %>
<% end %>

Clickable Badges

Add a URL to make badges clickable links. The badge automatically renders as an <a> tag.

<%= rui_badge(text: "View Profile", url: "/profile", color: :primary) do |badge| %>
  <% badge.with_icon(:user) %>
<% end %>

GitHub Style Badges

Special GitHub-themed badges using gh_ prefix colors.

<%= rui_badge(text: "ruby", color: :gh_topic) %>
<%= rui_badge(text: "rails", color: :gh_topic) %>

<%= rui_badge(text: "bug", color: :gh_label) %>
<%= rui_badge(text: "enhancement", color: :gh_label) %>

Real-World Examples

See how badges work in common UI patterns and real-world scenarios.

<%= rui_badge(text: "Pending", color: :warning, variant: :soft) do |badge| %>
  <% badge.with_icon(:clock) %>
<% end %>

<%= rui_badge(text: "Delivered", color: :success, variant: :soft) do |badge| %>
  <% badge.with_icon(:check_circle) %>
<% end %>

<div class="product-card">
  <h4>Premium Laptop</h4>
  <div class="flex flex-wrap gap-2">
    <%= rui_badge(text: "New Arrival", color: :success, size: :sm) %>
    <%= rui_badge(text: "Featured", color: :primary, size: :sm) %>
    <%= rui_badge(text: "Sale -20%", color: :danger, size: :sm, pulsing: true) %>
  </div>
</div>

<div class="flex items-center gap-2">
  <h5>John Doe</h5>
  <%= rui_badge(text: "Admin", color: :purple, size: :xs) %>
  <%= rui_badge(text: "Verified", color: :blue, size: :xs) do |badge| %>
    <% badge.with_icon(:badge_check) %>
  <% end %>
</div>

<div class="flex items-center gap-2">
  <span>Messages</span>
  <%= rui_badge(counter: 5, color: :danger, shape: :circle, size: :xs) %>
</div>

<%= rui_badge(text: "Category: Electronics", close_button: true, color: :blue, variant: :soft) %>
<%= rui_badge(text: "Price: $500-$1000", close_button: true, color: :blue, variant: :soft) %>

Accessibility

The Badge component follows WAI-ARIA best practices for status and label elements.

JavaScript API

The Badge component exposes Stimulus actions for programmatic control.

Stimulus Actions

Use these actions via data-action attributes:

<%# Badge with close button %>
<%= rui_badge("New", closeable: true) %>

<%# External control button %>
<button data-action="badge#toggle">Toggle Badge</button>

<%# Custom close behavior %>
<div data-controller="badge">
  <span class="...">Status</span>
  <button data-action="click->badge#close">×</button>
</div>

Programmatic Control

Control the badge from JavaScript using the Stimulus controller:

// Get the badge controller
const badgeElement = document.querySelector('[data-controller="badge"]')
const badgeController = application.getControllerForElementAndIdentifier(
  badgeElement,
  "badge"
)

// Toggle visibility
badgeController.toggle()

// Hide badge (keeps in DOM)
badgeController.dismiss()

// Remove from DOM
badgeController.close()

API Reference