LayrzChipGroup

LayrzChipGroup

A responsive container for multiple LayrzChip widgets with configurable overflow behavior.

Metadata
Mirrors: ThemedChipGroup (layrz_theme)
Phase: M2 (Core primitives)
Domain: Data
Primitive: SingleChildScrollView + Row
Status: Confirmed scope.

---

Overview

LayrzChipGroup manages the horizontal layout of multiple chips with two layout modes:

• .none (default): Chips render on a single horizontal row that scrolls when they overflow available width. No clipping, no overflow indicator.
• .compact: Chips are clamped to available width. When chips overflow, the remainder is collapsed into a single +N chip whose tooltip lists the hidden labels.

Use LayrzChipGroup to display lists of tags, filter badges, or dynamic label collections without manual overflow handling.

Design Principles

• Low friction for simple cases: Default .none mode requires no width constraint; it scrolls naturally.
• Constrained layouts: Use .compact mode when you need chips to fit within a fixed width (e.g., in a card, sidebar, or responsive container).
• Overflow indicator: The +N chip is context-colored (not configurable) and shows a tooltip listing the hidden chip labels when hovered or long-pressed.
• Measurement caveat (compact mode): The widget measures each chip individually to determine overflow, which costs one text layout per chip per build. Use sparingly in hot lists.

---

API Structure

Constructor

const LayrzChipGroup({
  required List<LayrzChip> chips,
  LayrzChipGroupBehavior behavior = LayrzChipGroupBehavior.none,
  double? spacing,
  Alignment alignment = Alignment.centerLeft,
  Key? key,
})

• chips (List, required) — The list of chips to display.
• behavior (LayrzChipGroupBehavior, default .none) — Layout behavior for overflow handling.
• spacing (double?, default null) — Space between each chip in logical pixels. When null, defaults to tokens.spacing.sp2 (8 logical pixels). Pass 0 for no spacing; pass any other value to override.
• alignment (Alignment, default Alignment.centerLeft) — Horizontal and vertical alignment of the chips. Only honored by .none behavior; .compact ignores this parameter.

---

LayrzChipGroupBehavior

Two layout modes:

enum LayrzChipGroupBehavior {
  /// Chips render on a single horizontal row that scrolls on overflow.
  ///
  /// This is the default behavior. Provides unlimited horizontal scrolling
  /// space without requiring a finite max-width constraint.
  none,

  /// Chips are clamped to available width; remainder collapses into +N.
  ///
  /// This behavior requires a finite max-width constraint (asserts otherwise).
  /// When overflow occurs, visible chips are shown, and any remaining chips
  /// are collapsed into a single +N chip whose tooltip lists the hidden labels.
  /// The N is clamped to 1–9.
  compact,
}

.none Mode

• Default behavior.
• Chips render on a single horizontal row.
• Scrolls naturally when overflow occurs (no clipping, no indicator).
• No width constraint required.
• alignment parameter is honored; chips can be aligned to start, center, end, or top/bottom.

.compact Mode

• Chips are measured and laid out within the available width.
• When overflow would occur, visible chips are shown, and the remainder is collapsed into a +N chip.
• Requires a finite maxWidth constraint; asserts if not provided (e.g., in an unbounded Column).
• alignment parameter is ignored; chips are always left-aligned.
• Tooltip on +N chip: Hovering or long-pressing the +N chip shows a tooltip listing all hidden chip labels, one per line.

Measurement caveat: In compact mode, the widget calls computeWidth() on each chip to measure its rendered size, then determines whether it fits within the available width. This costs one full text layout per chip per build. Avoid using .compact with very large chip lists in hot rebuild scenarios.

---

Examples

Basic Group (Default .none Mode)

LayrzChipGroup(
  chips: [
    LayrzChip(labelText: 'Flutter'),
    LayrzChip(labelText: 'Dart'),
    LayrzChip(labelText: 'Material Design'),
  ],
)

The chips render on a scrollable row. When the group is wider than the available space, users can scroll horizontally.

Compact Mode with Overflow Handling

SizedBox(
  width: 300,  // Constrained width
  child: LayrzChipGroup(
    chips: [
      LayrzChip(labelText: 'Tag 1'),
      LayrzChip(labelText: 'Tag 2'),
      LayrzChip(labelText: 'Tag 3'),
      LayrzChip(labelText: 'Tag 4'),
      LayrzChip(labelText: 'Tag 5'),
    ],
    behavior: LayrzChipGroupBehavior.compact,
  ),
)

If all five chips do not fit within 300 logical pixels, the visible chips are shown, and the remainder appears as +2 with a tooltip listing the hidden labels.

Custom Spacing

LayrzChipGroup(
  chips: [...],
  spacing: 12,  // Override default tokens.spacing.sp2
  behavior: LayrzChipGroupBehavior.none,
)

Alignment (.none Mode Only)

LayrzChipGroup(
  chips: [...],
  alignment: Alignment.center,  // Center chips horizontally
  behavior: LayrzChipGroupBehavior.none,
)

---

Notes

• Chips are always static: Even in a group, chips themselves are not selectable or interactive (except for the delete affordance on individual chips).
• Overflow indicator: In .compact mode, the +N chip is rendered as a context-colored chip with the label +N (where N is between 1 and 9). Tapping the +N chip does nothing; it is purely informational. Hover or long-press to see the tooltip.
• No reordering or rearrangement: Chips are displayed in the order they are provided. The group does not support dragging or reordering.
• .compact performance: Measuring each chip individually costs one layout per chip. For very large lists (100+ chips), prefer the .none mode with scrolling, or paginate the chips.

---

See Also

• LayrzChip — Individual chip widget