Table

Are you familiar with the pain of marking up HTML tables? I don't think I'll ever forget it. Fortunately, you'll never have to mark up another table again.

The Table component provides a dynamic table with sorting, search, and actions. Header rows are created dynamically from column names unless specified.

Preview

Code

import { Table } from 'components/lib';

function MyComponent({ ...props }){

  const data = [
    { id: 1, email: '[email protected]', date_created: '2023-01-01' },
    { id: 2, email: '[email protected]', date_created: '2023-01-02' },
  ];

  return (
    <div>
      <Table
        data={ data }
        searchable
        selectable
        show=['email', 'date_created']
      />
    </div>
  );
}

Props

Prop	Description	Required	Value
actions	array of action objects	optional	object (see below)
badge	add a badge to every row column	optional	object (see below)
data	array of table rows	required	object (see below)
footer	footer row	optional	object ({ span: integer, value: string })
header	array of header column names	optional	array (see below)
hide	columns names to hide	optional	array of strings
loading	toggle loading spinner	optional	boolean
searchable	enable searching the table data	optional	boolean
selectable	enable selecting table rows	optional	boolean
show	columns names to show	optional	array of strings
translation	reference to locale object for header translations	optional	string

Table Header Object

Pass a header array to the table if you'd like to customise the column headings. If no header is specified, Gravity will use the object key names from the first row and format them.

const header = ['Name', 'Email']

Table Data Object

The table body contains an array of objects - each array item generates a new row, and each key/value pair will be mapped to a column.

const data = [
  { id: 1, email: '[email protected]', date_created: '2023-01-01' },
  { id: 2, email: '[email protected]', date_created: '2023-01-02' },
];

Table Links

You can add a link to a table cell by passing an object with { label, url } keys.

const data = [
  { id: 1, email: { label: '[email protected]', url: '/users/1' }
];

Table Actions

The actions prop enables you to create a dropdown menu with action buttons for each table row. Global actions are also available by passing the global key with the optional globalOnly key to make this action available only in the global actions at the top of the table. Global actions can be performed on multiple rows when the selectable prop is passed to the table.

Global actions also accept a color key to set the button color.

Executing an action button will return the data of the row it belongs to so you can access IDs and values.

<Table
  data={ data }
  actions={{ 
  
    { icon: 'edit', label: 'Edit', action: editUser }, 
    { icon: 'trash', label: 'Delete, action: deleteUser }, 
    { icon: 'mail', label: 'Contact', action: contactUser },
    { icon: 'circle-plus', 'New', action: createUser, global: true, globalOnly: true, color: 'green' }
  
  }}
/>

Conditional Actions

You can conditionally render an action based on a cells value:

{ icon: 'edit', label: 'Edit', action: editUser, condition: { status: 'verified' }

Action Callbacks

Every action will return two callback helper functions: editRowCallback and deleteRowCallback to help with updating the table state once a row has been edited or deleted.

// edit row callback
const editUser = useCallback(({ row, editRowCallback }) => {

  viewContext.dialog.open({
    form: {
      inputs: {
        id: {
          type: 'hidden',
          value: row.id
        },
        email: {
          type: 'email', 
          value: row.email,
          required: true    
        },
        buttonText: 'Edit User',
        url: '/api/user',
        method: 'PATCH'
      }
    }, (form) => {

      const newState = editRowCallback(form);
      setUsers(newState);

  });
}, [viewContext])

// delete row callback
const deleteUser = useCallback(({ row, deleteRowCallback }) => {

  viewContext.dialog.open({
    form: {
      inputs: false,
      buttonText: 'Delete User',
      url: `/api/user/${row.id}`,
      method: 'DELETE',
      destructive: true
    },
  }, () => {

    const newState = deleteRowCallback(row);
    setUsers(newState);

  });
}, [viewContext]);

Table Badges

You can render a colored badge in your table rows using the badge prop. If you need to use conditional colors, pass an array of conditions and the table cell will test them. If you need multiple badges, you can pass an array of these objects.

badge={{ col: 'status', color: 'blue', condition: [

  { value: 'registered', color: 'green' },
  { value: 'invited', color: 'blue' }

]}}

Notes

• The Table component uses the Loader, Search, Icon, and cn functions from 'components/lib'.

• The actions prop specifies the actions that can be performed on the table rows.

• The badge prop allows for adding badges to specific columns based on conditions.

• The data prop provides the table rows.

• The footer prop specifies the footer row with a span and value.

• The header prop specifies the header column names.

• The hide prop allows for hiding specific columns.

• The loading prop toggles the loading spinner.

• The searchable prop enables the search field.

• The selectable prop allows users to select table rows and perform global actions.

• The show prop specifies the columns to show, defaulting to all.

• The translation prop refers to a locale object for header translations.

• For more details, refer to the Shadcn Table documentation.