Pill selector

Last updated: 2.0.0 (18/01/2024)

Usage

import { PillSelector } from "@valence-ui/core";

function MyComponent() { 
    const [value, setValue] = React.useState(["hello", "world"]);

    return ( 
        <PillSelector 
            value={value}
            setValue={setValue}
            pills={["hello", "there", "world"]}
        />
    )
}

Add new pills

To allow users to add new pills to this input, the allowEditing prop must be used. Additionally, the pills and setPills props must be tied to a React state, allowing them to be updated.

Allowing editing will create a new Text input above the Pill selector. Using this text editor, the user may type out a new pill and use the Enter key or the accompanying add button to create and select that pill. If the user then de-selects a pill they have created, it will be deleted from the list of pills as well.

The placeholder, inputProps, addButtonProps and addButtonIcon props can be used to modify the appearance and behavior of the inputs created when adding new pills.

import { PillSelector } from "@valence-ui/core";

function MyComponent() { 
    const [selected, setSelected] = React.useState(["hello", "world"]);
    const [pills, setPills] = React.useState(["hello", "there", "world"]);

    return ( 
        <PillSelector 
            value={selected}
            setValue={setSelected}
            
            pills={pills}
            setPills={setPills}
            allowEditing
        />
    )
}

Change wrap style

By default, the Pill selector will be formatted as a horizontally-scrolling series of pills, but the wrap prop exists to allow different wrapping of the input.

Setting wrap="wrap" allows the input to display every pill at once as a block:

import { PillSelector } from "@valence-ui/core";

function MyComponent() { 
    const [value, setValue] = React.useState(["hello", "world"]);

    return ( 
        <PillSelector 
            value={value}
            setValue={setValue}
            pills={["hello", "there", "world"]}
            
            wrap="wrap"
        />
    )
}

---

Props

Extends GenericInputProps<string[]> and PillSelectorEventProps.

Property	Type	Description
pills (required)	string[]	A list of pills to display.
setPills	(pills: string[]) => void	Optional callback to complete the state.
allowClear	boolean	Whether to allow pills to be cleared. true by default.
grow	boolean	Shorthand for flex-grow = 1
gap	number	Sets the gaps between everything. 5 by default.
wrap	CSSProperties["flexWrap"]	How the pills should wrap within their container. Defaults to "nowrap".
maxSelectable	number	The maximum number of pills that can be selected. Infinity by default.
clearButtonIcon	ReactNode	An icon to use for the clear button. Defaults to IconX
clearButtonProps	Omit<IconButtonProps, "children">	Optional props to pass to the clear button.
pillProps	Omit<TextButtonProps, "children">	Optional props to pass to all pills.
selectedPillProps	Omit<TextButtonProps, "children">	Optional props to pass to selected pills. Will override attributes from pillProps.
pillContainerProps	Omit<FlexProps, "children">	Optional props to pass to the pill container.
allowEditing	boolean	Whether to allow the creation of new pills.
placeholder	string	Placeholder text to display in the Text input. Will only show if allowEditing = true.
inputProps	Omit<TextInputProps, "value"|"setValue">	Optional styles to pass to the Text input.
addButtonProps	Omit<IconButtonProps, "children">	Optional props to pass to the add button.
addButtonIcon	ReactNode	Optional icon to use for the add button.

PillSelectorEventProps

Extends MouseClickEvents, MouseEvents, PointerEvents, FocusEvents and KeyboardEvents.

Property	Type	Description
onPillSelected	(value: string) => void	Callback to be fired when a pill is selected.
onPillDeselected	(value: string) => void	Callback to be fired when a pill is deselected.