List View

For development, import ListView from @servicetitan/anvil2. For design, find it in the Anvil2 file.

Anatomy

The List View consists of five primary elements that work together to display a selectable list with customization options.

Unselected
Label
Selected
Secondary Actions
Description

Options

The List View supports selection, secondary actions, disabled states, menus, and custom content configurations to accommodate various list scenarios.

Selection

Secondary action

Disabled

Custom content

Avatar

Description

Behavior

The List View responds to content overflow by wrapping labels to new lines while maintaining consistent list structure.

Overflow

When a List View label is too long for the available space, it wraps to a new line.

Usage Guidelines

Standard	Requirement
DoBuild lists of selectable items	List Views are used to construct lists of selectable items — for actions, navigation, and selections.
DoEmphasize multi-select with checkboxes	List Views are useful for emphasizing multiple selection with checkboxes.
DoAdd secondary actions to list items	Use List View when your list requires secondary actions, in addition to selecting multiple items or interacting with checkboxes. Unlike other options such as Listboxes, Comboboxes, or Side Nav menus, List View provides the functionality for these additional actions.

Alternatives

List View vs Listbox

Use Listbox when using simple selections that do not require any customization. Use List View when requiring customized styling or secondary actions. List View may also be used when emphasizing to users that multi-selection is possible.

How to Use

Choosing between secondary actions and menus

Choose secondary actions or menus based on the number of actions per item and their frequency of use. Use secondary actions when each item has one or two common actions that users access frequently. Secondary actions provide immediate access without additional clicks, making them ideal for primary workflows like editing or deleting items. Use menus when items have multiple actions or when actions are less frequently used. Menus reduce visual clutter and organize actions hierarchically, making them suitable for complex item management scenarios.

Organizing lists with custom content

Use custom content to provide visual context and additional information within list items. Avatars, descriptions, and other custom elements help users quickly identify and understand each option. Keep custom content focused and scannable to maintain list clarity and usability.

Content

Content within the List View should clearly communicate each option and provide necessary context through labels and descriptions.

Keyboard Interaction

Users can navigate the List View using standard keyboard controls.

Code

Implementation
ListView Props
ListView.Option Props

Common Examples

import { ListView, Text } from "@servicetitan/anvil2";

function ExampleComponent() {
  return (
    <ListView>
      <ListView.Option label="first">
        <Text>First Value</Text>
      </ListView.Option>
      <ListView.Option label="second">
        <Text>Second Value</Text>
      </ListView.Option>
      <ListView.Option label="third">
        <Text>Third Value</Text>
      </ListView.Option>
    </ListView>
  );
}

Creating selectable list views

The ListView component can be used to easily create selectable lists using the label prop and custom content as children of each ListView.Option.

Indeterminate list views

The indeterminate prop can be used when the selection of items is controlled to render the checkbox as indeterminate, instead of checked or not checked. This is useful when building a nested structure.Note: the logic to determine which items are indeterminate is not included, since there are various use cases. Simply pass the items that should be indeterminate to the prop.

Using items objects with list views

The items prop of a ListView can also be passed an array of objects which are passed to the children of the list view. Each item object should have a label, but any other arbitrary attributes are allowed.

const Items = [
  { label: "Item 1", imgUrl: "#" },
  { label: "Item 2", imgUrl: "#", disabled: true },
  { label: "Item 3" },
];

export const ListViewExample = () => (
  <ListView items={Items}>
    {(items) =>
      items.map((item) => (
        <ListView.Option key={item.label} item={item} disabled={item.disabled}>
          <Avatar image={item.imgUrl} name={item.label} />
          <Text>{item.label}</Text>
        </ListView.Option>
      ))
    }
  </ListView>
);

<ListView
  items={itemsArray}
  defaultSelected={[]}
  selected={[]}
  indeterminate={[]}
  onSelectionChange={(value) => console.log(value)}
>
  {(items) =>
    items.map((item) => (
      <ListView.Option key={item.label} item={item}>
        {item.label}
      </ListView.Option>
    ))
  }
</ListView>

`ListView` Props

In addition to the props listed below, the ListView component can accept any valid HTML div props.

(value: unknown[]) => void

required

Callback when the selection changes.

(items) => ReactNode (items prop only) ReactNode (without items prop)

If the items prop is used, ListView’s children will be a function that passes the items.

ItemType[] (items prop only) string[] (without items prop)

ItemType[]

Items passed to this prop will render with an indeterminate checkbox (controlled)

ItemType[]

ListView can be used with or without an items prop to manage your list of items

ItemType[]

Items passed to this prop will render with an checked checkbox (controlled)

<ListView.Option
  item={item}
  label="Option 1"
  disabled={false}
  onChange={(e) => console.log("Changed")}
>
  Option content
</ListView.Option>

`ListView.Option` Props

In addition to the props listed below, the ListView.Option component can accept any valid HTML div props.

boolean

{ label: string, defaultSelected?: boolean, [keys]: values }

Required if no label prop is supplied.

string

Required if no item prop is supplied.

(e: ChangeEvent) => void

Concepts & Guidelines

Anvil2

Resources

List View - Web

Anatomy

Options

Selection

Secondary action

Disabled

Menu

Custom content

Avatar

Description

Behavior

Overflow

Usage Guidelines

Alternatives

List View vs Listbox

How to Use

Choosing between secondary actions and menus

Organizing lists with custom content

Content

Keyboard Interaction

Code

Common Examples

Creating selectable list views

Indeterminate list views

Using items objects with list views

`ListView` Props

`ListView.Option` Props

​Anatomy

​Options

​Selection

​Secondary action

​Disabled

​Menu

​Custom content

​Avatar

​Description

​Behavior

​Overflow

​Usage Guidelines

​Alternatives

​List View vs Listbox

​How to Use

​Choosing between secondary actions and menus

​Organizing lists with custom content

​Content

​Keyboard Interaction

​Code

​Common Examples

​Creating selectable list views

​Indeterminate list views

​Using items objects with list views

​ListView Props

​ListView.Option Props

Anatomy

Options

Selection

Secondary action

Disabled

Menu

Custom content

Avatar

Description

Behavior

Overflow

Usage Guidelines

Alternatives

List View vs Listbox

How to Use

Choosing between secondary actions and menus

Organizing lists with custom content

Content

Keyboard Interaction

Code

Common Examples

Creating selectable list views

Indeterminate list views

Using items objects with list views

`ListView` Props

`ListView.Option` Props