All components (244)

People picker

Choice · PeoplePicker

What it is and when to use it

Choosing several people: who gets invited to a meeting, who goes in a group, who a ticket is assigned to. It is a MultiSelect with the people inside: each option carries its avatar with the presence dot, the name and a line underneath, and each chosen one comes out as a chip with its avatar.

When to use it

Inviting, assigning, sharing: anywhere people are chosen from a known list.
people carries each person with their key, their name, their photo (src), their presence (status) and a description (the role, the team).
exclude with the keys of whoever is already in the group: they are not offered, since choosing them twice makes no sense.
Those online go first, which is who is usually being looked for; byPresence={false} leaves the order they arrive in.
Everything from MultiSelect still applies: max, limitTags, serverFiltered and onType to search on the server, loading...

When not to

Choosing a single person: Select with renderOption and an Avatar inside.
Showing who is there, without choosing: AvatarGroup.

Keyboard: that of MultiSelect: type to filter, the arrows go through the list, Enter chooses, Backspace removes the last chip and Tab goes through each chip and its cross.

Accessibility: what is read is the name, and the presence goes as the option's description ("Marta Ruiz, Management · online"): the coloured dot alone does not tell it. The avatars inside are decorative, the name is already written next to them.

Fine appearance: no variables of its own; it uses the field ones (--amset-field-*) and the classes amset-people__option, amset-people__name, amset-people__description and amset-people__tag.

What it looks like

Assign to

Marta Ruiz

<PeoplePicker
  label="Assign to"
  people={personas}
  placeholder="Search for someone on the team"
  byPresence
  initialValue={["marta"]}
/>

Props

Import it with import { PeoplePicker } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`label`required	`string`	—
`people`required	`readonly Person[]`	—
`allowsCreate`	`boolean`	Allows creating values that are not in the list (free-form tags).
`byPresence`	`boolean`	Sorts by presence (online first) and then by name. With `false`, the order they arrive in.
`checklist`	`boolean`	Checklist mode: the list keeps showing what is chosen with its mark, pressing a chosen one removes it and the panel stays open so you can tick several in a row. On reaching `max`, the ones still unticked are disabled instead of disappearing.
`className`	`string`	Merged with the library classes; it does not replace them.
`disabled`	`boolean`	Nothing can be typed, the list does not open and chips cannot be removed: everything leaves the Tab order.
`error`	`string`	—
`exclude`	`readonly string[]`	Keys that are not offered: whoever is already in the group, whoever is inviting themselves.
`hint`	`string`	—
`initialValue`	`readonly string[]`	—
`invalid`	`boolean`	Marks the field as invalid. The normal thing is to pass `error`, which also explains it.
`limitTags`	`number`	How many chips are shown while the field is at rest; the rest are summed up as "+N" and all of them appear when the field is entered. Without it all are shown, and the box grows in lines when they do not fit.
`loading`	`boolean`	The options are arriving. Marks the field as busy, shows a ring and a `loadingText` row in the list; the options that were already there stay.
`loadingText`	`string`	What the loading row says. "Loading…" by default.
`max`	`number`	How many can be chosen at most.
`maxVisibleOptions`	`number`	Cap on the options painted at once in very long lists (thousands). The rest are not painted: the list says how many are shown and to type to narrow down. Without it, all are painted.
`name`	`string`	The name under which the choice travels in a native form: one hidden field per key (`name=a&name=b`), like a `<select multiple>`.
`noResultsMessage`	`string`	—
`offset`	`number`	—
`onChange`	`(keys: readonly string[]) => void`	—
`onType`	`(text: string) => void`	—
`placeholder`	`string`	—
`placement`	`Placement`	—
`readOnly`	`boolean`	What is chosen is shown and the field can be focused, but nothing is added or removed: the chips lose their remove button.
`removeText`	`(label: string) => string`	The whole name of the button that removes each chip: "Remove Rings" by default. It is the entire name; nothing is appended to it.
`required`	`boolean`	—
`serverFiltered`	`boolean`	The list already arrives filtered from outside (server-side search).
`size`	`"sm" \| "md" \| "lg"`	—
`value`	`readonly string[]`	Chosen keys. If passed, the state is managed by whoever uses the component.
`variant`	`FieldVariant`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: