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.

Client-side collections

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.

Server-side collections

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.

Code example

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

'use client';
import React, { useState } from 'react';
import { useCollection } from '@cloudscape-design/collection-hooks';
import {
  Box,
  Button,
  CollectionPreferences,
  Header,
  Pagination,
  Table,
  TextFilter,
} from '@cloudscape-design/components';
import allItems from './data';
import { columnDefinitions, getMatchesCountText, paginationLabels, collectionPreferencesProps } from './table-config';

function EmptyState({ title, subtitle, action }) {
  return (
    <Box textAlign="center" color="inherit">
      <Box variant="strong" textAlign="center" color="inherit">
        {title}
      </Box>
      <Box variant="p" padding={{ bottom: 's' }} color="inherit">
        {subtitle}
      </Box>
      {action}
    </Box>
  );
}

export default function CollectionHooksTable() {
  const [preferences, setPreferences] = useState({
    pageSize: 10,
    contentDisplay: [
      { id: 'id', visible: true },
      { id: 'availabilityZone', visible: true },
      { id: 'state', visible: true },
    ],
  });
  const { items, actions, filteredItemsCount, collectionProps, filterProps, paginationProps } = 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>}
          />
        ),
      },
      pagination: { pageSize: preferences.pageSize },
      sorting: {},
      selection: {},
    }
  );
  const { selectedItems } = collectionProps;
  return (
    <Table
      {...collectionProps}
      selectionType="multi"
      header={
        <Header
          counter={selectedItems.length ? `(${selectedItems.length}/${allItems.length})` : `(${allItems.length})`}
        >
          Instances
        </Header>
      }
      columnDefinitions={columnDefinitions}
      columnDisplay={preferences.contentDisplay}
      items={items}
      pagination={<Pagination {...paginationProps} ariaLabels={paginationLabels} />}
      filter={
        <TextFilter
          {...filterProps}
          countText={getMatchesCountText(filteredItemsCount)}
          filteringAriaLabel="Filter instances"
        />
      }
      preferences={
        <CollectionPreferences
          {...collectionPreferencesProps}
          preferences={preferences}
          onConfirm={({ detail }) => setPreferences(detail)}
        />
      }
    />
  );
}

Using expandable rows

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.

Using multi-select tokens

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.
          ':',
          '!:',
        ],
        // ...
      }
    ]
  }
});

Using custom operator matchers

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.

Intercepting event listeners

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