GrChipGroup — Components

Overview

When to take it

the filters of a list in a line — statuses, categories, labels: every option is visible at once, and several may be selected;
a choice among short options instead of a list — the period of a report, a priority: there are up to a dozen options, and there is no point hiding them under a button;
a set of labels on a record that is edited in place — closable gives every chip a cross, and Delete removes the one under focus;
a form field whose value is a set — the group reads the context of GrFormField and gives its value to a native form by name.

When to take something else

Need	Take
A single choice, few options, the look of a switch	`GrSegmented`
A single choice with descriptions on the options	`GrRadioGroup`
Multiple selection as a list with marks	`GrCheckboxGroup`
There are dozens of options, searched by typing	`GrSelect` / `GrAutocomplete`
A row of dismissible labels without selection	`GrChip` without a group

Variants every tone and view, rendered by the real component

Variants · GrChipGroup
`tone` \ `dark`	`false`	`true`
`primary`
`neutral`
`success`
`warning`
`danger`
`info`
`slate`
`azure`

Sizes

xs
sm
md
lg

States

normal
disabled
readonly
invalid

The grid is live: hover and press it. Hover, focus and active states are not drawn here — they belong to the browser, not to a prop.

Playground controls come from the API, not from hand

Stage

Loading…

0 changed· state is in the URL

Examples 4 each with a live demo and its code

Catalogue filters, several and one
Rooms and materials combine, so their groups keep an array — a listbox with one Tab stop and arrows inside. Delivery is one of two or any: selection="single" makes a radiogroup, and clicking the chosen chip again resets it to null, which the page reads as «any delivery date».
Room
Material
Delivery
3 desks · any delivery date
- Halden desk
- Brekka standing desk
- Lune vanity
- Orsa writing desk
- Tove kids desk
- Kalla corner desk
A priority in a ticket form
Each priority has its own meaning, so each chip has its own tone. Inside GrFormField the group takes the label and the required state from the field, and name puts the value into the native form — submit it and see the form data.
New ticketCard declined on renewal · Northwind Traders
Priority
form data appears here
Three highlights at most
The group never caps the selection: the limit is the app’s rule, so the app refuses the fourth pick and says why. closable gives each chip a cross named after it, Delete removes the focused one, and remove is only a request — the page takes the skill out of its list.
SkillsPick up to three to highlight · Delete removes the focused one
1 highlight left
The first question after sign-up
size="lg" and radius="round" make a row that is easy to hit on a phone; the group passes tone to every chip, and a selected chip takes the solid fill of the same hue. A disabled chip stays readable, so «Payroll · soon» is seen rather than missed.
What will you use Acme Billing for?Pick all that apply — we will set up the workspace around them

API generated from the package · cannot drift

Props

Prop	Type	default	Description
`disabled`	`boolean \| undefined`	`false`	The set is unavailable: the chips cannot be selected or dismissed. Also switched on by `GrFormField`.
`tone`	`"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "` `"primary" \| "neutral" \| "success" \| "warning" \| "danger" \| "info" \| "slate" \| "azure" \| undefined`	`undefined`	The tone of all the chips in the set; the prop of a chip is stronger. Not set — `GrConfigProvider`, otherwise `neutral`.
`closable`	`boolean \| undefined`	`false`	A cross on every chip of the set. It is overridden pointwise by the prop of a chip.
`modelValue`v-model	`GrChipValue \| GrChipValue[] \| null \| undefined`	`undefined`	A single selection is a value, a multiple one is an array.
`readonly`	`boolean \| undefined`	`false`	The selection is visible but does not change.
`invalid`	`boolean \| undefined`	`false`	A value with an error: `aria-invalid` on the group. Also switched on by an error of `GrFormField`.
`required`	`boolean \| undefined`	`false`	A selection is required: `aria-required` on the group. Also switched on by `GrFormField`.
`size`	`"xs" \| "sm" \| "md" \| "lg" \| undefined`	`undefined`	A step of the scale for all the chips in the set; the prop of a chip is stronger. `md` by default.
`ariaLabel`	`string \| undefined`	`undefined`	The accessible name of the set. Not needed inside `GrFormField`: the label of the field names the group.
`name`	`string \| undefined`	`undefined`	The name for a native form. A multiple selection gives one field per value.
`dark`	`boolean \| undefined`	`undefined`	A fill in the tone instead of a soft surface for all the chips in the set; the prop of a chip is stronger.
`radius`	`GrBadgeRadius \| undefined`	`undefined`	The shape of all the chips in the set: `round`, `semi` or `square`; the prop of a chip is stronger.
`selection`	`GrChipSelection \| undefined`	`"multiple"`	How many can be selected: `multiple` — an array of values and the `listbox` role, `single` — one value or `null` and the `radiogroup` role. `multiple` by default.

Slots

Slot	Type	Description
`default`	`any`	The chips of the set.

Events

Event	Signature	Description
`update:modelValue`	`(event: "update:modelValue", value: GrChipValue \| GrChipValue[] \| null): void`	—
`change`	`(event: "change", value: GrChipValue \| GrChipValue[] \| null): void`	—
`focus`	`(event: "focus", event: FocusEvent): void`	—
`blur`	`(event: "blur", event: FocusEvent): void`	—
`remove`	`(event: "remove", value: GrChipValue): void`	—

Methods

Methods	Signature	Description
`focus`	`() => void \| undefined`	Focus on the active chip — the one that holds the `Tab` stop of the set.
`blur`	`() => void \| undefined`	Remove focus from the active chip of the set.

Types

Every exported type of the subpath, grouped by the file it lives in. Names, generics and bodies come from the package’s declaration files and cannot drift.

Import

import type { GrChipGroupConfigurableProps, GrChipGroupProps, GrChipGroupEmits } from '@feugene/granularity/components/GrChipGroup'

Filedist/types/components/GrChipGroup/config.d.ts

grChipGroupConfigconst

const grChipGroupConfig: import("@feugene/granum/contract").GranumComponentDescriptor<"GrChipGroup">;

Filedist/types/components/GrChipGroup/defaults.d.ts

GrChipGroupConfigurablePropsinterface

interface GrChipGroupConfigurableProps {
    size: GrChipSize;
}

Filedist/types/components/GrChipGroup/safelist.d.ts

grChipGroupSafelistconst

const grChipGroupSafelist: string[];

Filedist/types/components/GrChipGroup/GrChipGroup.vue.d.ts

GrChipGroupPropsinterface

interface GrChipGroupProps {
    modelValue?: GrChipValue | GrChipValue[] | null;
    selection?: GrChipSelection;
    name?: string;
    disabled?: boolean;
    readonly?: boolean;
    invalid?: boolean;
    required?: boolean;
    closable?: boolean;
    size?: GrChipSize;
    tone?: GrChipTone;
    radius?: GrChipRadius;
    dark?: boolean;
    ariaLabel?: string;
}

GrChipGroupEmitsinterface

interface GrChipGroupEmits {
    (e: 'update:modelValue', value: GrChipValue | GrChipValue[] | null): void;
    (e: 'change', value: GrChipValue | GrChipValue[] | null): void;
    (e: 'remove', value: GrChipValue): void;
    (e: 'focus', event: FocusEvent): void;
    (e: 'blur', event: FocusEvent): void;
}

Filedist/types/components/GrChipGroup/index.d.ts

GrChipGroupInstancetype

type GrChipGroupInstance = ComponentExposed<typeof GrChipGroupComponent>;

Usage from the library prose

The role depends on the multiplicity of the selection

selection="multiple" (the default) declares the group a listbox with aria-multiselectable, and the chips option with aria-selected. selection="single" gives a radiogroup and radio with aria-checked, as in GrSegmented.

The chips get their role from the context and do not choose it themselves: otherwise a set of chips with different roles would be announced to a screen reader as anything but one widget.

One Tab stop, inside it the arrows

The group is composite, so it occupies one stop in the tab order: the active chip holds tabindex="0", the rest -1. The arrows work along both axes — chips wrap onto a new line, and “down” means the next chip just as “right” does. Home/End take you to the edges.

An arrow moves the focus only, even in single mode. Chips have a second action — dismissal with Delete — and moving the selection along with the focus would mean changing the model while trying to reach the chip you want. In a form radiogroup the opposite is customary, but there the elements have a single action.

Selecting again clears the mark

In single mode a click on an already selected chip resets the value to null. A set of filters with no value selected makes sense (“any”), and there would otherwise be no way to cancel the selection — unlike form switches, where an empty value is usually forbidden.

The contents are drawn by the consumer

The group has no options prop: every chip has a label, an icon and a tone of its own, and generating them from a flat array would mean introducing a second, poorer way to describe the same thing. Hence remove as well — the group only relays it, and the application removes the item from the array.

Limits

the group has no order of its own — it draws the chips in the order of the slot;
the group does not limit the number selected. The limit is a rule of the application, and so is the message about it: the group does not know what to show instead of a refusal;
there are no nested groups. A set inside a set poses an unanswerable question about whose arrow is handled.