PlChip

A compact token: a tag, a filter, a status, an entity plucked out of a list. It can carry a count, be pressed, be removed, or all three at once.

React

import { PlChip } from 'plass-ui';

<PlChip>design</PlChip>;
<PlChip selected onClick={toggle} count={12}>
  open
</PlChip>;
<PlChip onDelete={remove}>infra</PlChip>;

import 'package:plass_ui/plass_ui.dart';

const PlChip(child: Text('design'));
PlChip(selected: on, onPressed: toggle, count: const Text('12'), child: const Text('open'));
PlChip(onDeleted: remove, child: const Text('infra'));

Props

Prop	Type	Default	Description
variantshared	'solid' | 'glass' | 'ghost'	'glass'	What the surface is made of. A chip is the thing being coloured, so its sheet takes the tint. glass by default: a row of gradient keys is a row in which nothing is the primary action
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	One step down the control ladder — a md chip is a sm control, 32px rather than 40px, because a chip is a token inside a row rather than a control the row lines up against
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'default'	Padding only — never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
startIcon	ReactNode	—	Content placed before the label — an icon, a status dot, an avatar
endIcon	ReactNode	—	Content after the label, before any count
count	ReactNode	—	A number set into the end of the chip, on its own small plate, so "Errors 12" reads as one token with a count rather than as two words
onClick	(event: MouseEvent) => void	—	Passing it turns the label into a real button. The shell stays a span: a button inside a button is invalid HTML that browsers un-nest on parse
onDelete	(event: MouseEvent) => void	—	Passing it is what makes the delete button appear — a second real button with its own tab stop, separate from the label
deleteLabel	string	'Remove'	Accessible name of the delete button. Never drawn
selected	boolean	false	A filter that is on. It moves one step up the ladder its own variant already sits on rather than changing the colour family — a filter that is on is still the same filter
disabledshared	boolean	false	Unavailable. The light goes out, the same way it does everywhere else
children	ReactNode	—	The label

Prop	Type	Default	Description
variantshared	PlassVariant	PlassVariant.glass	What the surface is made of. A chip is the thing being coloured, so its sheet takes the tint. glass by default: a row of gradient keys is a row in which nothing is the primary action
sizeshared	PlassSize	PlassSize.md	One step down the control ladder — a md chip is a sm control, 32px rather than 40px, because a chip is a token inside a row rather than a control the row lines up against
colorshared	PlassColor	PlassColor.primary	Semantic colour role. Arbitrary colour values are not accepted
densityshared	PlassDensity	PlassDensity.standard	Padding only — never the height, never the type scale
elevationshared	int	0	Drop shadow depth. 0 means no shadow at all
startIcon	Widget?	—	Content placed before the label — an icon, a status dot, an avatar
endIcon	Widget?	—	Content after the label, before any count
count	Widget?	—	A number set into the end of the chip, on its own small plate, so "Errors 12" reads as one token with a count rather than as two words
onPressed	VoidCallback?	—	Passing it turns the label into a real button. The shell stays a span: a button inside a button is invalid HTML that browsers un-nest on parse
onDeleted	VoidCallback?	—	Passing it is what makes the delete button appear — a second real button with its own tab stop, separate from the label
deleteLabel	String	'Remove'	Accessible name of the delete button. Never drawn
selected	bool	false	A filter that is on. It moves one step up the ladder its own variant already sits on rather than changing the colour family — a filter that is on is still the same filter
disabledshared	bool	false	Unavailable. The light goes out, the same way it does everywhere else
child	Widget?	—	The label

Every native <span> attribute passes straight through, onto the shell. color is excluded from the pass-through because it is a Plass prop here.

count is a Widget? rather than a number, because unlike a badge's it is never capped. The plate holds whatever it is given.

What the shared axes (variant size color density elevation) mean across the library is in prop conventions.

Examples

onClick and onDeleteonPressed and onDeleted

The shell is always a <span>. What changes is what is inside it: a plain run of content, or (when onClick is given) a real <button> wrapping that content, plus a second button for onDelete.

That is not indirection. A <button> inside a <button> is invalid HTML that browsers un-nest on parse, so keeping the shell a <span> is what lets "activate this chip" and "remove this chip" both be real, focusable buttons.

A chip that can be pressed and a chip that can be removed are two separate focus stops, and neither is inside the other's gesture recogniser. The reason is the same one the React build has for keeping the shell a <span>, arrived at from the other end: a tap that reached both would fire both.

A chip with no onPressed takes no focus stop and is announced as content rather than as a button. It is a tag, and a tag is not something you press.

React

import { useState } from 'react';
import { PlChip } from 'plass-ui';

export default function ChipInteractive() {
  const [on, setOn] = useState(true);

  return (
    <div className="flex flex-wrap items-center gap-3">
      <PlChip>Not pressable</PlChip>
      <PlChip selected={on} onClick={() => setOn(!on)}>
        Pressable
      </PlChip>
      <PlChip onDelete={() => {}}>Removable</PlChip>
      <PlChip onClick={() => {}} onDelete={() => {}}>
        Both
      </PlChip>
      <PlChip disabled onClick={() => {}}>
        Disabled
      </PlChip>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ChipInteractive extends StatefulWidget {
  const ChipInteractive({super.key});

  @override
  State<ChipInteractive> createState() => _ChipInteractiveState();
}

class _ChipInteractiveState extends State<ChipInteractive> {
  bool _on = true;

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 12,
      runSpacing: 12,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        const PlChip(child: Text('Not pressable')),
        PlChip(
          selected: _on,
          onPressed: () => setState(() => _on = !_on),
          child: const Text('Pressable'),
        ),
        PlChip(onDeleted: () {}, child: const Text('Removable')),
        PlChip(onPressed: () {}, onDeleted: () {}, child: const Text('Both')),
        PlChip(disabled: true, onPressed: () {}, child: const Text('Disabled')),
      ],
    );
  }
}

variant

A chip is the thing being coloured, a tag names one particular thing, so unlike a PlCard its sheet takes the tint. ghost keeps a wash at rest rather than being bare, which is the difference between a token and a control: a ghost button has nothing until the pointer arrives.

glass is the default rather than solid. A filter bar is a row of chips, and a row of gradient keys is a row in which nothing is the primary action because everything is.

React

import { PlChip } from 'plass-ui';

export default function ChipVariants() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {(['solid', 'glass', 'ghost'] as const).map((variant) => (
        <PlChip key={variant} variant={variant}>
          {variant}
        </PlChip>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ChipVariants extends StatelessWidget {
  const ChipVariants({super.key});

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 12,
      runSpacing: 12,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        for (final variant in PlassVariant.values)
          PlChip(variant: variant, child: Text(variant.name)),
      ],
    );
  }
}

selected

Chosen moves the chip one step up the ladder its own variant already sits on, rather than changing the colour family: a filter that is on is still the same filter.

solid has no opacity ladder to climb, because a gradient fill is the fill. So it answers the other way the design language allows, it casts its own colour onto the sheet under it. A chosen key lifts; an unchosen one lies flat.

React

import { PlChip } from 'plass-ui';

export default function ChipSelected() {
  return (
    <div className="flex flex-col gap-4">
      {(['solid', 'glass', 'ghost'] as const).map((variant) => (
        <div key={variant} className="flex flex-wrap items-center gap-3">
          <span className="w-14 text-xs text-(--plass-muted-fg)">{variant}</span>
          <PlChip variant={variant} onClick={() => {}}>
            off
          </PlChip>
          <PlChip variant={variant} selected onClick={() => {}}>
            on
          </PlChip>
        </div>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ChipSelected extends StatelessWidget {
  const ChipSelected({super.key});

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      mainAxisSize: MainAxisSize.min,
      spacing: 16,
      children: <Widget>[
        for (final variant in PlassVariant.values)
          Row(
            mainAxisSize: MainAxisSize.min,
            spacing: 12,
            children: <Widget>[
              SizedBox(
                width: 56,
                child: PlTypography(variant.name, level: PlTypographyLevel.caption),
              ),
              PlChip(variant: variant, onPressed: () {}, child: const Text('off')),
              PlChip(variant: variant, selected: true, onPressed: () {}, child: const Text('on')),
            ],
          ),
      ],
    );
  }
}

startIcon, endIcon and count

count is drawn on its own small plate, so "Errors 12" reads as one token with a count rather than as two words.

React

import { PlAvatar, PlChip } from 'plass-ui';

function DotIcon() {
  return (
    <svg viewBox="0 0 16 16" aria-hidden="true">
      <circle cx="8" cy="8" r="4" fill="currentColor" />
    </svg>
  );
}

export default function ChipSlots() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <PlChip startIcon={<DotIcon />} color="success">
        Deployed
      </PlChip>
      <PlChip startIcon={<PlAvatar size="xs" name="Ada Lovelace" />} color="secondary">
        Ada Lovelace
      </PlChip>
      <PlChip count={12} color="danger">
        Errors
      </PlChip>
      <PlChip variant="solid" count="99+">
        Unread
      </PlChip>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

/// A filled disc, which is the whole glyph a status chip needs.
class _Dot extends StatelessWidget {
  const _Dot();

  @override
  Widget build(BuildContext context) {
    final theme = IconTheme.of(context);
    final size = theme.size ?? 16;

    return SizedBox.square(
      dimension: size,
      child: DecoratedBox(
        decoration: BoxDecoration(
          shape: BoxShape.circle,
          color: theme.color ?? const Color(0xFF000000),
        ),
        child: Center(child: SizedBox.square(dimension: size / 2)),
      ),
    );
  }
}

class ChipSlots extends StatelessWidget {
  const ChipSlots({super.key});

  @override
  Widget build(BuildContext context) {
    return const Wrap(
      spacing: 12,
      runSpacing: 12,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        PlChip(startIcon: _Dot(), color: PlassColor.success, child: Text('Deployed')),
        PlChip(
          startIcon: PlAvatar(size: PlassSize.xs, name: 'Ada Lovelace'),
          color: PlassColor.secondary,
          child: Text('Ada Lovelace'),
        ),
        PlChip(count: Text('12'), color: PlassColor.danger, child: Text('Errors')),
        PlChip(variant: PlassVariant.solid, count: Text('99+'), child: Text('Unread')),
      ],
    );
  }
}

color

React

import { PlChip } from 'plass-ui';

export default function ChipColors() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {(['primary', 'secondary', 'success', 'warning', 'danger', 'info'] as const).map((color) => (
        <PlChip key={color} color={color}>
          {color}
        </PlChip>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ChipColors extends StatelessWidget {
  const ChipColors({super.key});

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 12,
      runSpacing: 12,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        for (final color in PlassColor.values) PlChip(color: color, child: Text(color.name)),
      ],
    );
  }
}

size

A chip sits one step down the control ladder from everything else: a md chip is a sm control, 32px rather than 40px. At full control height a glass chip and a glass button are the same object, and a screen full of them says nothing about which one can be pressed.

React

import { PlChip } from 'plass-ui';

export default function ChipSizes() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <PlChip key={size} size={size}>
          {size}
        </PlChip>
      ))}
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class ChipSizes extends StatelessWidget {
  const ChipSizes({super.key});

  @override
  Widget build(BuildContext context) {
    return Wrap(
      spacing: 12,
      runSpacing: 12,
      crossAxisAlignment: WrapCrossAlignment.center,
      children: <Widget>[
        for (final size in PlassSize.values) PlChip(size: size, child: Text(size.name)),
      ],
    );
  }
}

Accessibility

• A chip with onClick is a real <button> carrying aria-pressed, so a filter that is on says so. A chip without one adds no role and takes no tab stop. An inert <span> with a click handler on it is the single most common way a component library loses its keyboard users.
• The label and the delete button are two separate tab stops, and neither is nested inside the other.
• The delete button has an accessible name already; deleteLabel is what changes it.
• disabled stops the label from being a button at all rather than leaving a focusable one that does nothing, and marks the shell aria-disabled so the state is still announced.

• A chip with onPressed is announced as a button and reports whether it is selected, so a filter that is on says so. A chip without one adds no role and takes no focus stop.
• The label and the delete affordance are two separate focus stops, and neither is inside the other.
• The delete affordance has a name already, "Remove"; deleteLabel is what changes it.
• Enter, Space and the numpad Enter activate a pressable chip. They are bound on the chip itself, so it behaves the same with or without an app widget above it.
• disabled takes the chip out of the focus order and stops it firing, and the delete affordance with it.

Differences from the React build

React	Flutter	Why
onClick	onPressed	Flutter's name.
onDelete	onDeleted	Flutter's name for the same slot.
a <button> inside a <span>	two sibling focus stops	The same shape for the same reason. HTML forbids the nesting; here a nested recogniser would take one tap twice.
count as a ReactNode	count as a Widget?	The same thing, spelled in Flutter.
className, style	—	There is no class list and no style attribute to pass through.