Collection API

Examples

Basic Example

The ListBox on its own isn't very useful. It registers each item with the model. The ListBox.Item only uses the useListItemRegister hook which handles registration of static items to the model. The ListBox uses useListRenderItems which handles rendering static items as well as dynamic items.

Identifying Items

A list item takes an optional data-id property that will be used to identify an item. Without a data-id, the identifier will be the item's index when first registered. The basic example has a data-id attribute that is a string representation of the index. Providing a data-id will override to a value of your choosing. This identifier will be used by other hooks to identify the item for selection, maintaining a cursor, or anything else.

Dynamic Items

The ListBox also handles a dynamic collection of items. Instead of providing each ListBox.Item statically, provide a render function instead. The function is called with an item value that is the same as what's provided to the model.

Registering Items

Dynamic items can be passed in as an array of strings or objects via the items prop or the model config.

Array of Strings

Use strings when your data is a simple list of options. Each string value is used as the unique identifer.

Array of Objects

Use objects when your data contains additional information. Each object must have an id to ensure it's registered and searchable. Additional information such as icons or if the item is disabled can be included in the object and will be accessible in the render function.

Note: The id should match your text value for each item. This ensures proper selection of items in components like Select and Autocomplete. If your id is different from your text value, you'll have to add a translation layer.

Virtualization

By default, providing items dynamically will enable virtualization. This example adds a maxHeight to ensure overflow. Virtualization uses absolute positioning of each item, which could cause problems for popup menus. If your item count is low, pass shouldVirtualize={false} to disable virtualization.

DataLoader

The collection system comes with a data loader to help with dynamic collections. You must provide total, pageSize, and an asynchronous load function. The loader will call the load function when the user navigates the collection and needs more data. This example shows how to hook up a simple data loader and mocks a load function to simulate an asynchronous response.

The data loader also takes a model argument to know which model to create. The loader configures the model to handle asynchronous keyboard navigation and will return the configured model to you to pass along to the collection component.

Roving Tabindex

The list system also includes a cursor that extends the list. A cursor is mostly used for focusing items. The roving tabindex is a well-supported way to accomplish accessibility requirements for focusing items within a list. This example shows how to use useListRovingFocus. This example uses the ListBox component, but the default ListBox.Item is very basic. We have two options, we can either pass additional functionality via elemPropsHook or by creating a new item using our elemProps hook primitives. Both will be demonstrated. Creating a custom item is recommended if you create a custom component and export it. Using elemPropsHook with ListBox.Item is recommended only for one-off instances.

You can either use the tab key for focus on an item or click on an item and then use the up/down keys to navigation the list. By default, the list is set to wrap navigation using the wrappingNavigationManager. Only a single item in the list is a focus stop that "roves" as the up/down arrows are pressed.

Note: This example doesn't meet accessibility requirements. The list will have to have some type of context. Like "navigation list" or "menu list".

Selection

Lists support selection. useSelectionItem is applied to an item which adds an onClick that adds the item to the state.selectedIds. The default selection manager is a single select. This example uses ListBox and creates a custom SelectableItem elemProps hook and component.

String Children

Sometimes it is desired to allow the string children to be the identifiers for each item. This could be useful for autocomplete components where the item's text is the desired identifier. Normally, if no data-id is provided to the item, the system will choose the registration index. This would be '0', '1', and so on. By passing useListItemAllowChildStrings to an item component, it will change this behavior to use the child text if no data-id is provided.

Multiple Selection

The selection manager can be passed directly to the model configuration to handle different selection types. This example passes the multiSelectionManager to handle selecting multiple items.

Basic Grid

A grid is a two dimensional list. A columnCount config is added to inform how to break up an array of items. A grid is very similar to a list - it receives items as a single dimension list and uses the columnCount to determine keyboard navigation. Grids only support a single orientation.

Wrapping Grid

By default, navigating a grid does not wrap around when the user reaches the end of a row or column. The grid model supports passing in a navigation manager. The collection system supports two types of navigation managers, a non-wrapping navigationManager and the wrappingNavigationManager. The following example passes the wrappingNavigationManager manager to the model. Observe how the cursor wraps around columns and rows when an edge of a column or row is encountered.

Component API

ListBox

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

const useMyItem = composeHooks(
  useListItemSelect, // additional hooks go here
  useListItemRegister // always last
);

const list = useListModel({
  // custom handling for selection. single and multi select are provided
  selection: mySelectionManager,
  // wrapping and non-wrapping navigation are provided
  navigation: myNavigationManager,
  items: [{ id: '1', text: 'First'}, { id: '2', text: 'Second' }],
  getId: item => item.id, // get the unique identifier of your item
})

Navigation Manager

navigationManager

The navigationManager implements the Navigation Manager interface for lists and grids, but does not wrap when the user hits a boundary of the collection. This is the default navigation manager for grids.

wrappingNavigationManager

The wrappingNavigationManager implements the Navigation Manager interface for lists and grids, and wraps when the user hits a boundary of the collection. Grids will wrap columns, but not rows. This is the default navigation manager for lists.

Selection Manager

Hooks

const useMyItem = composeHooks(
  useListItemSelect, // additional hooks go here
  useListItemRegister // always last
);

const useMyListItem = composeHooks(
  // any other hooks here
  useListItemSelect,
  useListItemRegister,
  useListItemAllowChildStrings // always the last in the list
)


<MyList onSelect={({id}) => {
  console.log(id) // will be "First" or "Second"
}}>
  <MyList.Item>First</MyList.Item>
  <MyList.Item>Second</MyList.Item>
</MyList>

const useMyItem = composeHooks(
  useListItemRovingFocus, // adds the roving tabindex support
  useListItemRegister
);

const useMyItem = composeHooks(
  useListItemSelect, // adds selection support to an item
  useListItemRegister
);

const MyList = createContainer('ul')({
  modelHook: useListModel,
})((elemProps, Element, model) => {
  return <Element {...elemProps}>{useListRenderItems(model, elemProps.children)}</Element>;
});

const useMyItem = composeHooks(
  useListResetCursorOnBlur, // adds the cursor reset to selected for roving tabindex
  useListItemRovingFocus,
  useListItemRegister
);

const useMyItem = composeHooks(
  useOverflowListItemMeasure,
  useListRegisterItem,
)

const {model, loader} = useListLoader(
  {
    total: 1000,
    pageSize: 20,
    async load({pageNumber, pageSize}) {
      return fetch('/myUrl')
        .then(response => response.json())
        .then(response => {
          return {total: response.total, items: response.items};
        });
    },
  },
  useListModel
);