Collection hooks package

Cloudscape provides table and cards components to display collections of resources. These components display static datasets. Operations on these datasets (such as filtering, sorting, and pagination) should happen outside of these components.

The @cloudscape-design/collection-hooks package provides utilities to handle filtering, sorting, or pagination operations when the full dataset describing the collection can be fetched on the client side, without requiring further asynchronous calls. This use case is called client-side collection.

If your dataset has to be fetched asynchronously upon filtering, sorting, and pagination operations, don’t use the @cloudscape-design/collection-hooks package. Instead, implement the fetching, filtering, selection, pagination, and sorting yourself. This use case is called server-side collection.

This package is published to NPM as @cloudscape-design/collection-hooks .

For more information, see the package installation guide.

This package exports the useCollection React hook . It takes the original collection items and a configuration, and returns filtered, sorted, and paginated content, according to your configuration.

Example below uses text filtering. Check out the official demo that uses property filtering feature of the collection hooks.

If you want to use sorting, filtering, or property filtering on items that include nested properties, such as item.name.first and item.name.last, transform the items to bring the nested properties to the top:

allItems = allItems.map(item => ({ ...item, firstName: item.name.first, lastName: item.name.last }));

const { items, collectionProps, filterProps, actions } = useCollection(allItems, {
  filtering: {
    empty: <EmptyState title="No instances" action={<Button>Create instance</Button>} />,
    noMatch: <EmptyState title="No matches" action={<Button onClick={() => actions.setFiltering('')}>Clear filter</Button>} />,
  },
  sorting: {},
});

// The sorting and filtering now include item.firstName and item.lastName

If you want a table to use hierarchical data presentation with expandable rows, define nested items structure with expandable rows configuration of the useCollection hook:

const allItems = [
  { id: '1', type: 'group', name: 'Devices', parentId: null },
  { id: '1.1', type: 'device', name: 'Smartphone', parentId: '1' },
  { id: '1.2', type: 'device', name: 'Laptop', parentId: '1' },
  { id: '2', type: 'group', name: 'Auxillary', parentId: null }
];

const { items: rootItems, collectionProps } = useCollection(allItems, {
  expandableRows: {
    getId: (item) => item.id,
    getParentId: (item) => item.parentId,
  }
});

return (<Table items={rootItems} columnDefinitions={columnDefinitions} {...collectionProps} />);

Note that it is important to define expandable rows via collection hooks so that filtering, sorting, and pagination work correctly.

To use multi-select tokens, pass tokenType="enum" to the desired properties and operators. For example:

const { items, propertyFilterProps, ... } = useCollection({
  propertyFiltering: {
    filteringProperties: [
      {
        key: 'state',
        operators: [
          // Set token type for equals and not equals operators as enum so that
          // the default many-to-one matching logic is used.
          // In the property filter, the corresponding multi-choice form and formatter will be used.
          { operator: '=',  tokenType: "enum" },
          { operator: '!=', tokenType: "enum" },
          // Keep token type for contains and not contains operators as is.
          ':',
          '!:',
        ],
        // ...
      }
    ]
  }
});

If you want to override the default filtering logic, use a match function on the extended operator notation:

const { items, propertyFilterProps, ... } = useCollection({
  propertyFiltering: {
    filteringProperties: [
      // Using custom matcher to support searching with a comma-separated list
      {
        key: 'status',
        operators: [
          { operator: '=', match: (itemValue, tokenValue) => tokenValue.split(',').includes(itemValue) },
          { operator: '!=', match: (itemValue, tokenValue) => !tokenValue.split(',').includes(itemValue) },
        ],
        ...
      },
      // Using predefined date matcher
      {
        key: 'launchDate',
        operators: [
          { operator: '=', match: 'date' },
          { operator: '!=', match: 'date' },
          { operator: '<', match: 'date' },
          { operator: '<=', match: 'date' },
          { operator: '>', match: 'date' },
          { operator: '>=', match: 'date' },
        ],
        ...
      },
      // Using predefined datetime matcher
      {
        key: 'lastEventAt',
        operators: [
          { operator: '=', match: 'datetime' },
          { operator: '!=', match: 'datetime' },
          { operator: '<', match: 'datetime' },
          { operator: '<=', match: 'datetime' },
        ],
        ...
      },
    ]
  }
});

Note that overrides are done per operator.

If you want to define a custom behavior upon user actions, ensure you always call the method created by the collection hook:

const { ..., paginationProps } = useCollection(...);
    
return (
  <Table
    ...
    pagination={
      <Pagination
        {...paginationProps}
        onChange={event => {
          myCustomFunction(event);
          paginationProps.onChange(event);
        }}
      />
    }
  />
);

useCollection(allItems: Array, configuration: Configuration): Result