Pill Manager
Use the Pill Manager to manage data items, selection, order, and state using a list of pills with drag-and-drop support.
LyteNyte Grid exports PillManager, a headless component with composable parts.
Assemble the parts for manual customization, or use the default configuration.
You can use the PillManager to control different aspects of the grid, for example:
- Use the
PillManagerto control column visibility and column order by toggling pills and reordering them. - Use the
PillManagerto manage and reorder row groupings. - Use pills to select from a list of labels to support label filters.
- Combine multiple pill rows to create a column pivot configuration UI.
The example below demonstrates a complete setup. The remaining sections of this guide explain the
individual capabilities of the PillManager component.
Pill Manager Component
Pill Manager Anatomy
The PillManager component is a headless component. Similar to LyteNyte Grid, it supports
two rendering modes:
- Headless Mode:
PillManagerexposes its component parts for full custom configuration. - Default Mode:
PillManagerrenders using a built-in default configuration.
<PillManager> {(row) => { return ( <PillManager.Row row={row}> <PillManager.Label row={row} /> <PillManager.Container> {row.pills.map((pill) => { return <PillManager.Pill />; })} </PillManager.Container> <PillManager.Expander /> </PillManager.Row> ); }}</PillManager><PillManager />Pill Row Specification
PillManager requires the rows property to be an array of PillRowSpec objects. Each
PillRowSpec object is rendered as a row containing pills.
The PillRowSpec and PillItemSpec interfaces are shown below.
export interface PillItemSpec { /** A unique ID for an individual pill. */ readonly id: string; /** Whether the pill is enabled. */ readonly active: boolean; /** The display name of the pill. */ readonly name?: string; /** Whether the pill can be reordered or moved to another pill row. */ readonly movable?: boolean; /** Tags that other pill rows can accept. */ readonly tags?: string[]; /** Any data to associate with the pill item. */ readonly data?: unknown; /** Whether the pill can be removed. */ readonly removable?: boolean;}
export interface PillRowSpec { /** A unique ID for the row. */ readonly id: string; /** The list of pills contained in the row. */ readonly pills: PillItemSpec[]; /** External pill tags that this row accepts. */ readonly accepts?: string[]; /** A human-readable label for the row. */ readonly label?: string; /** A preset style for the pills, or a custom string. */ readonly type?: "columns" | "row-groups" | "row-pivots" | "column-pivots" | "measures" | ({} & string);}Pill Active State
Set the active property on every PillItemSpec in a PillRowSpec.
The active property determines whether a pill is enabled. The semantic meaning
of active is defined by your use case.
The demo below uses active to toggle column visibility, where inactive pills appear dimmed.
Pill Manager State
When a pill’s active state changes, the PillManager calls the
onPillRowChange handler. Use the provided parameters shown below to update your row state.
type onPillItemActiveChange = (params: { readonly index: number; readonly item: PillItemSpec; readonly row: PillRowSpec;}) => void;Pill Reordering
Set the movable property on a pill to enable reordering. By default, a pill can be
reordered within its own pill row. By setting the tags property, you can indicate that
a pill may also be moved to another row. For another row to accept a pill, set the
accepts property on the row to include one of the tags from the pill being moved.
The demo below demonstrates pill reordering. You can drag pills between sections to activate them, or reorder pills within the same row.
Pill Manager Reordering
When pills are reordered, the PillManager calls the onPillRowChange event handler.
The handler type is shown below.
- The
changedproperty contains thePillRowSpecobjects that were updated. - The
fullproperty contains allPillRowSpecobjects, with their pills updated to reflect the completed move.
type onPillRowChange = (params: { readonly changed: PillRowSpec[]; readonly full: PillRowSpec[] }) => void;Pill Parts
All parts are rendered using a render prop provided to the PillManager. The render prop is optional. If you do not provide it, the PillManager uses a default implementation.
Pill Row
The PillManager.Row component is a container for an individual pill row. Each
PillRowSpec provided to the PillManager results in a rendered pill row. The
PillManager.Row component requires a PillRowSpec.
<PillManager> {(row) => { return <PillManager.Row row={row} />; }}</PillManager>Pill Label
The PillManager.Label component renders the label for each pill row. If you do not
provide a label, PillManager renders a default PillManager.Label based on the
pill row’s type.
<PillManager> {(row) => { return ( <PillManager.Row row={row}> <PillManager.Label row={row} /> </PillManager.Row> ); }}</PillManager>Pill Container
The PillManager.Container component renders all pills for a given row. It also acts as
the drop zone for external pills. All PillManager.Pill components must be rendered
inside a PillManager.Container.
<PillManager> {(row) => { return ( <PillManager.Row row={row}> <PillManager.Label row={row} /> <PillManager.Container /> </PillManager.Row> ); }}</PillManager>Pill
The PillManager.Pill component renders a single pill. A pill is the primary interaction
element of the PillManager. You must render each PillManager.Pill inside a
PillManager.Container.
<PillManager> {(row) => { return ( <PillManager.Row row={row}> <PillManager.Label row={row} /> <PillManager.Container> {row.pills.map((pill) => ( <PillManager.Pill key={pill.id} item={pill} /> ))} </PillManager.Container> </PillManager.Row> ); }}</PillManager>Pill Expander
The PillManager.Expander toggles the display mode of a pill row between a scrollable
view and a wrapped view. When expanded, all pills in the row are visible.
<PillManager> {(row) => { return ( <PillManager.Row row={row}> <PillManager.Label row={row} /> <PillManager.Container> {row.pills.map((pill) => ( <PillManager.Pill key={pill.id} item={pill} /> ))} </PillManager.Container> <PillManager.Expander /> </PillManager.Row> ); }}</PillManager>Vertical Pills
Set the orientation property on the PillManager to “vertical” to orient pills vertically.
The demo below demonstrates this configuration. Since the PillManager is headless, you must
apply the appropriate styles when rendering a vertical layout.
Vertical Pill
Pill Manager Styling
PillManager is unstyled by default. Import the prebuilt LyteNyte Grid styles
to align PillManager with the rest of the grid. These styles also provide
pill theming for each PillRowSpec type.
import "@1771technologies/lytenyte-pro/pill-manager.css";Pill Manager Properties
All PillManager component parts render as HTML elements and accept standard HTML props.
This section lists the additional properties that each component supports.
PillManager
Prop
PillManager.Row
Prop
PillManager.Label
Prop
PillManager.Pill
Prop
PillManager.Expander
Prop
Next Steps
- Tree View: Render and interact with hierarchical data using the Tree View component.
- Smart Select: Streamline data selection using a versatile combobox or select element.
- Row Group Cell: Handle expansion and collapse interactions for grouped rows.
