useSelectable hook

The NewTable API has behaviors like selecting and sort extracted into hooks.

You can attach these hooks to your table to enhance the experience. We want to stress that the usage of these hooks is completely optional, you can create all of these behaviors on your own and by hand.

The objective is to cover the majority of the cases with the hooks and other APIs but still have the option of overwriting any default, creating flexibility.

This hook provides functionality to make it easier to build tables with selectable rows. It handles the logic of managing checkbox states.

The hook receives your data Array and an optional config Object with the following type definition:

type ConfigObject = {
  /* An unique attribute of the elements in the data array. Default: 'id' */
  key?: string,
  /* An array of unique identifiers that will be initially selected */
  initialState?: Array<string>,
}

Keep in mind that the key needs to be a unique value, otherwise the hook will select multiple values with the same key.

() => {
  const data = [
    { id: "123", stakeholder: "Emily Wilson", email: "emily.wilson@carta.com", security: "ES-161" },
    { id: "234", stakeholder: "Tagg Palmer", email: "tagg.palmer@carta.com", security: "ES-262" },
    { id: "456", stakeholder: "Bruce Banner", email: "bruce.banner@avengers.com", security: "ES-456" },
  ];
  const [selected, actions] = useSelectable(data, { initialState: ["123"] });
  return (
    <NewTable data-testid="newtable-selectable">
      <NewTable.Head>
        <NewTable.Row>
          <NewTable.HeadCell>
            <NewCheckbox id="select-all" checked={selected.allRows} onChange={actions.toggleAllRows} />
          </NewTable.HeadCell>
          <NewTable.HeadCell>Stakeholder</NewTable.HeadCell>
          <NewTable.HeadCell>Security</NewTable.HeadCell>
        </NewTable.Row>
      </NewTable.Head>
      <NewTable.Body>
        {data.map((d) => (
          <NewTable.Row key={d.id} selected={selected.rows[d.id]}>
            <NewTable.Cell preset="checkbox">
              <NewCheckbox id={d.id} onChange={actions.toggleRow} checked={selected.rows[d.id]} />
            </NewTable.Cell>
            <NewTable.Cell>{d.stakeholder}</NewTable.Cell>
            <NewTable.Cell>{d.security}</NewTable.Cell>
          </NewTable.Row>
        ))}
      </NewTable.Body>
    </NewTable>
  );
}

// state
export type UseSelectableStateType = {
  /* Array of selected `keys` */
  rows: any,
  /* Boolean that indicates if all rows are selected */
  allRows: boolean,
}

// actions
export type UseSelectableActionsType = {
  /* Set state for a particular set of selected rows (use with caution) */
  setSelectedRows: Dispatch<SetStateAction<any>>,
  /* Callback for single Checkboxes */
  toggleRow: (event: ChangeEvent<HTMLInputElement>) => void,
  /* Callback for select all Checkboxes */
  toggleAllRows: () => void,
  /* Helper function that returns the props that the NewTable.Row needs to work with the hook.
   * You can also pass this by hand as we did in the example above. */
  getSelectRowProps: (data: any) => GetSelectRowPropsType,
  /* Helper function that returns the props that the Checkbox needs to work with the hook.
   * You can also pass this by hand as we did in the example above. */
  getSelectProps: (data: any) => GetSelectPropsType,
  /* Helper function that returns the props that the select all Checkboxes needs to work with the hook.
   * You can also pass this by hand as we did in the example above. */
  getSelectAllProps: () => GetSelectAllPropsType,
  /* Helper function that returns an array of selected keys. */
  getSelectedKeys: () => string[],
  /* Helper function that returns an array of selected data instances. */
  getSelectedItems: () => any[],
}