LyteNyte Grid logo for light mode. Links back to the documentation home page.
Components

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 PillManager to control column visibility and column order by toggling pills and reordering them.
  • Use the PillManager to 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

Column Pivots
Age Group
Gender
Country
State
Product
Category
Sub-Category
Row Pivots
Country
Age Group
Gender
State
Product
Category
Sub-Category
Measures
Profit
Quantity
Price
Cost
Revenue
Fork code on stack blitzFork code on code sandbox

Pill Manager Anatomy

The PillManager component is a headless component. Similar to LyteNyte Grid, it supports two rendering modes:

  • Headless Mode: PillManager exposes its component parts for full custom configuration.
  • Default Mode: PillManager renders 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>

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

Columns
Symbol
Network
Exchange
Change % 24h
Perf % 1W
Perf % 1M
Perf % 3M
Perf % 6M
Perf % YTD
Volatility
Volatility 1M
Fork code on stack blitzFork code on code sandbox

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

Column Pivots
Age Group
Gender
Country
State
Product
Category
Sub-Category
Row Pivots
Country
Age Group
Gender
State
Product
Category
Sub-Category
Fork code on stack blitzFork code on code sandbox

When pills are reordered, the PillManager calls the onPillRowChange event handler. The handler type is shown below.

  • The changed property contains the PillRowSpec objects that were updated.
  • The full property contains all PillRowSpec objects, 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

Column Pivots
Age Group
Gender
Country
State
Product
Category
Sub-Category
Row Pivots
Country
Age Group
Gender
State
Product
Category
Sub-Category
Measures
Profit
Quantity
Price
Cost
Revenue
Fork code on stack blitzFork code on code sandbox

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.