MultiColumnList

MultiColumnList

Renders an array of data objects as a table where each object is a row and each property of the objects is a column. Capable of virtualizing rows in large collections of data.

Basic Usage

const catalogResults = [
    {title:'Microbiology Today', author:'James Edward'},
    {title:'Orange Book', author:'Philip Ramos'},
]

<MultiColumnList contentData={catalogResults} />

You can also specify a formatter object to control exactly how the data is rendered: see below.

Sticky Columns

The first and last columns of the grid can be 'pinned' into place. These will keep them visible when they would normally have scrolled out of view. To apply this, use the stickyFirstColumn or stickyLastColumns props.

Infinite scroll

For large lists of data the boolean prop virtualize can be turned on to efficiently display only the table rows that are visible to the user within the scrollable body of the list. The virtualize prop should be used in conjunction with the height, maxHeight or autosize prop - virtualization will not work otherwise.

Sparse Array Support

Currently for non-virtualized (non-infinite scroll) lists, MCL can render sparse array structures. Sparse arrays are simply arrays that don't have their entire length's worth of data items.

Height and autosize props

For efficiency, virtualization of list items requires a static height value (not percentage-based). If you're unsure how large the list's containing element will be, you can set the autosize prop to true - this will make the grid dynamically fill the space that it has, automatically using the resulting static width and height. This is ideal for the content of results panes.

Horizontal scroll

The list will scroll its content horizontally if there isn't enough horizontal room to display all of the columns.

Column mapping

MultiColumnList supports column header mapping via. the columnMapping-prop. This allows for mapping column headers to alternative strings. This is very useful for translating column headers.

Note: The recommended text casing for column headers is sentence casing. Read more about language rules here.

Here's an example from the Users-module:

  <MultiColumnList
    contentData={...}
    visibleColumns={['actionDate', 'action', 'dueDate', 'itemStatus', 'source']}
    columnMapping={{
      action: <FormattedMessage id="ui-users.loans.columns.action" />,
      actionDate: <FormattedMessage id="ui-users.loans.columns.actionDate" />,
      dueDate: <FormattedMessage id="ui-users.loans.columns.dueDate" />,
      itemStatus: <FormattedMessage id="ui-users.loans.columns.itemStatus" />,
      source: <FormattedMessage id="ui-users.loans.columns.source" />,
    }}
  />

Column Widths

MultiColumnList measures DOM elements at render-time to calculate a single width for the entire column. At a minimum, this will be the width of the column's header. Render-time measurement is not always the preferred way to go, so MultiColumnList has the columnWidths prop for pre-determined widths to be applied. This will also avoid calculation of widths for pre-determined columns at render-time. For columns where the column content width may vary, space conservation is important. For this, the width 'hint' API can be used.

const columnWidths = {
  name: '200px',
  jobTitle: { min: 30, max: 300 },
  startDate: '300px'
}

<MultiColumnList ... columnWidths={columnWidths} />

Advice #1: Use a pre-determined width if there's a large amount of difference between a column's contents from one row to another. For instance, "title" items could contain a single word, or it could contain 10 words. Calculation will prefer a width that's closer to the longest among the sampled cells, so setting a width is the best way to keep the widths modest.

Advice #2: Prefer pixel px values to percent values. You can apply any CSS unit you'd like, in the columnWidths prop, but percents % are less practical and often result columns being overly squeezed with content growing very tall in comparison to other columns of the row.

Storybook examples

Check out our hosted storybook for examples of usage. Source code for these stories is all available in the MultiColumnList stories directory.

Properties

Name	type	description	default	required
autosize	bool	if true, list will size itself to fit its containing element. Use this to have a list occupy the full width and height of a <Pane>s content area.	false
columnIdPrefix	string	Appends a prefix to the id's for column headers and clickable headers for buttons. Useful in case multiple grids with the same shape of data appear in the same view.
columnMapping	object	Maps rendered column labels to the data fields for the onHeaderClick prop.	{}
columnWidths	object	Set custom column widths, e.g. {email: '150px'}. Component will automatically measure any columns that are unspecified. An object can be provided with min and max keys to set up a range - MCL will pick as close to the min as it can and none over the max.
contentData	array of object	the list of objects to be displayed.		required
dataEndReached	bool	Used in conjuction with pagingType="click", dataEndReached can be used if a suitable totalCount prop cannot be obtained. Setting this to true will render the "end-of-list" marker rather than the load button.	false
dndProvided	object	The provided object provided by the <Droppable> context contains a placeholder for the draggable row. Used for MCLs supporting Drag-n-Drop.	{}
formatter	object mapping names to functions	see separate section
getCellClass	func	Used to update or completely overwrite the visual styles for each column. The function passed to this prop will receive the current CSS class, row data and the column name as the parameters and the returned value will overwrite the default class – e.g. (defaultClass, rowData, header) => ${defaultClass} ${myCustomClass}	undefined
getHeaderCellClass	func	Used to update the visual styles for each column header. The function passed to this prop will receive the column name as the parameter and the returned value will extend the default class – e.g. header => ${myCustomClass}	undefined
getRowContainerClass	func	Used to update the visual styles for row container. The function passed to this prop will receive the current CSS class as the parameter and the returned value will overwrite the default class – e.g. defaultClass => ${defaultClass} ${myCustomClass}	undefined
hasMargin	bool	Applies horizontal margin on rows and header. This is primarily used to achieve the correct spacing within result panes.
headerMetadata	object	Object with data to include with the
headerRowClass	string	Applies a css class to the header row of the list.
height	string or number	the height of the table. Necessary if virtualize is active you aren't using autosize already.
interactive	bool	Applies a "pointer" cursor when the mouse hovers over a row	true
isEmptyMessage	string, object, node, arrayOf(node)	Message to display when the supplied contentData array is empty.
itemToView	positionObject	This object has keys for a 'selector' (string) and a client offset (number, pixels). This object is used to scroll the MCL list to the item that matches the selector, visually positioning it at the client offset from the top of the MCL. This is currently only working for non-virtualized lists.	null
isSelected	func({item})	Should return true or false on whether or not to apply the selectedClass to the row. Useful for multiple selections. Preferred over selectedRow
loading	bool	If true, will display an animated loading icon.
maxHeight	number	the maximum height that the list should grow to before scrolling its list body in pixels.
nonInteractiveHeaders	array of strings	Pass an array of column names to make their column headers non-interactive. This is only relevant if you have supplied an onHeaderClick-callback and you only want some of the header columns to be interactable.	[]
onHeaderClick	func[event, headerMetadata]	callback function invoked when one of the cells in the header is clicked (typically to choose a sort-order). By default, headerMetadata includes the column's data name as well as its alias, in case a object is supplied to the columnMapping prop.
onMarkPosition	func(positionObject)	Called when an item is focused within the list. The position object consists of a 'selector' string and a client-space offset in pixels. This can be fed back to the itemToView prop and, upon rendering the list, MCL will scroll to the item, maintaining the same visual position. itemToView is currently only working for non-virtualized lists.
onMarkReset	func	Called if the selector of the ItemToView isn't found. Modules can use this to reset their cached value.
onNeedMoreData	func(askAmount, index)	Callback for fetching more data. If this prop is provided and a totalCount prop is provided, but un-reached by the count of loaded data items, askAmount will ask for the remainder of items or the pageAmount prop, whichever is less. This can be used to fulfill limit query parameters. rowIndex can be used to fulfill an offset query parameter.
onRowClick	function(event, item)	callback function invoked when one of the lines in the table is clicked (typically to select a record for more detailed display).
onScroll	func	Callback for scrolling of list body.	noop
pageAmount	number	The base amount of data to pass as the askAmount parameter for the onNeedMoreData prop	30
pagingCanGoNext	bool	When passed to component, will enable or disable "Next" pagination button. When null or undefined - default checking for available next page will be performed	null
pagingCanGoPrevious	bool	When passed to component, will enable or disable "Previous" pagination button. When null or undefined - default checking for available previous page will be performed	null
pagingOffset	number	Sets the 'offset' of pagination numbers if the pagingType is set to prev-next. A pagingOffset of 100 will render 101 as the starting index in the UI. It works in conjuction with the length of contentData and the totalCount prop to render a beginning and ending number for the content of the list.
pagingType	string	Controls the interaction type when loading more data in the MCL. "scroll" is used for infinite scroll/loading scenarios, "click" renders a paging button below the results if the loaded count is less than the totalCount prop. prev-next will render pagination with 'previous' and 'next' buttons with a display of the current page's item numbers."none" is used for custom pagination	"scroll"
rowFormatter	func	function of shape <name>({rowIndex, rowClass, rowData, cells, rowProps}){return <reactElement>} that can be used to supply custom row layout. Forking defaultRowFormatter is a good place to start if you need to use this.	defaultRowFormatter
rowMetadata	array	a list of keys in contentData that should not be rendered. This is useful if you wish to add arbitrary data outside of the realm of the rendered MCL, such as for the onRowClick handler.	[]
rowUpdater	func(rowData, rowIndex)	This function should return a shallow data structure (flattened object) or primitive (string, number) that will indicate that exterior data for a row has changed. It will receive two parameters of the rowData and the rowIndex that can be used to base return values. This result is fed directly to the data rows via props, keeping them pure. You should rarely have to use this prop, as most changes will be relayed directly in the contentData array itself.	noop
selectedClass	string	override class for the default style applied to selected rows.	built-in
selectedRow	object	legacy API Applies 'selected' class to the table row matching the property in the object, e.g. {id: '1224'}.
showSortIndicator	bool	If true, an icon for sortable fields will be displayed next to the column name. It will not be displayed for the currently sorted column. Also add the sortableFields property so that screen readers can read all column names, not just those not in nonInteractiveHeaders.	false
sortableFields	array	A list of sortable field names, allowing the sort indicator to be displayed for sortable fields rather than those not in nonInteractiveHeaders.	[]
sortedColumn	string	Used to apply styling to the appropriate column.
sortDirection	string	'ascending' or 'descending' direction.
stickyFirstColumn	bool	Pins the first column in place so that it will remain visible when scrolled out of view.
stickyLastColumn	bool	Pins the last column in place so that it will remain visible when scrolled out of view
striped	bool	Adds striped style to rows	true
totalCount	number	The total number of expected records. It's necessary in various situations: using virtualize (so that MCL can anticipate the dimensions of expected rows) and with prev-next and click paging types ( so that the 'next' or 'load more' button can be adequately disabled when the end of the list is reached.)	0
virtualize	bool	Employs virtualization for performant rendering of large sets of data.	0
visibleColumns	array of strings	an ordered list of column names, indicating which fields from each object should be included in the table. (When omitted, the keys from the first record are used.)

Usability: Clickable Rows vs clickable cells

Using both types of interaction is not good for users or developers, so it's best to simply use one or the other. For clickable cell content, place clickable elements within formatters. Clickable rows are easily created by using the onRowClick prop.

Formatter

Formatters allow for specific control of how data is rendered. Given the following data:

catalogResults = [
        { title: 'Biology Today',
          id: '199930490002',
          author: {
            firstName: 'James',
            lastName: 'Whitcomb',
          },
        },
        { title: 'Financial Matters',
          id: '199930490034',
          author: {
            firstName: 'Philip',
            lastName: 'Marston',
          },
        },
        { title: 'Modern Microbiotics',
          id: '199930490064',
          author: {
            firstName: 'Eric',
            lastName: 'Martin',
          },
        },
      ];

A formatter object can be used to render the author.firstName and author.lastName properties concatenated inside the corresponding table cell. Each property of the formatter object contains a function that returns a string or JSX element to be rendered:

const resultsFormatter = {
      author: item => `${item.author.firstName} ${item.author.lastName}`,
    };

<MultiColumnList
    contentData={catalogResults}
    formatter={resultsFormatter}
    visibleColumns={['title', 'author']}
/>

Side-effects in formatters

Efficient performance of MCL depends on rows being "Purely" rendered - no exterior data used aside from what is directly supplied to the formatters themselves in the item argument. Doing so is discouraged and problematic. If an instance is using "impure" techniques, rows may not update as you would expect them to. Two suggestions for handling this:

1. Actually include the exterior data into your contentData prop if possible.
2. Use the rowUpdater prop to have MCL rows detect/render the changes.

  // for 'active' rows, pass in a data item for another list at the corresponding index... otherwise, return null.
  rowUpdater = (rowData, rowIndex) => {
    return rowData.active ? otherData[rowIndex] : null;
  }

Formatting Rows

It's possible to modify the rendered mark-up of rows using the rowFormatter prop. If one of these is needed, the best place to start is a fork of defaultRowFormatter. Here's an example that wraps rows in anchor tags instead of the default div:

// utility function to fill anchor's href attribute...
getRowURL(rowData){
  return `url/with/${rowData.info}`;
}

// custom row formatter function
anchoredRowFormatter(
    { rowIndex,
      rowClass,
      rowData,
      cells,
      rowProps,
      labelStrings,
    }
  ){
    return (
      <a
        href={this.getRowURL(rowData)} key={`row-${rowIndex}`}
        aria-label={labelStrings.join('...')}
        role="listitem"
        className={rowClass}
        {...rowProps}
      >
        {cells}
      </a>
    );
  }

// and the JSX...

<MultiColumnList
  // ...other props
  rowFormatter={this.anchoredRowFormatter}
/>