Data

container and context provider for data driven content

Data simplifies the process of managing and presenting data driven content. It establishes a context that tracks which filters, search, and sort controls have been applied. Using that, it determines what subset of the data should be rendered.

Data provides smart defaults for what kind of filter to render for a property based on the type of data and number of unique options.

Type	Number of options	Default filter
string	Less than 5	CheckBoxGroup
string	5 or more	SelectMultiple
number	--	RangeSelector

If a custom filter type is desired, this can be done using a compositional approach, where you provide your own component as a child to DataFilter.

<Data>
  <DataFilters>
    <DataFilter property="a">
      <MyCustomFilter />
    </DataFilter>
 </DataFilters>
</Data>

Props

data

Array of data objects.

array

[
  {
    id: 1, 
    name: 'Scott', 
    age: 24,
    siblings: ['Scarlet', 'Scout'],
    contact: {
      company: 'Acme, Inc.',
      social: '@scotty',
    },
  },
  {
    id: 2, 
    name: 'Zelsa', 
    age: 91,
    siblings: ['Zack', 'Zoe', 'Zelda', 'Zed', 'Ziggy'],
    contact: {
      company: 'Retired',
    },
  },
]

defaultView

The default view of the data.

object

{
  properties: {
    country: ['US', 'UK'],
    age: {
      min: 22,
      max: 56,
    },
  },
  search: 'com',
  sort: {
    property: 'date',
    direction: 'desc',
  },
  page: 1,
  step: 50,
  columns: ['country']
}

filteredTotal

The total number of objects that exist in the data set AFTER any filtering has been applied. This should be used when retrieving data from a paged API where the number of objects in 'data' is only one page and the filtered set of data is larger than a page.

number

id

A unique identifier for the Data. This is required if more than one Data is rendered on the page.

string

"data_1"

messages

Custom messages for Data related components.

object

{
  "dataFilters": {
    "clear": "Clear filters",
    "heading": "Filters",
    "open": "Open filters",
    "openSet": {
      "singular": "Open filters, {number} filter applied",
      "plural": "Open filters, {number} filters applied"
    }
  },
  "dataForm": {
    "submit": "Apply filters"
  },
  "dataSearch": {
    "label": "Search",
    "open": "Open search"
  },
  "dataSort": {
    "ascending": "Ascending",
    "by": "Sort by",
    "descending": "Descending",
    "direction": "Sort direction",
    "open": "Open sort"
  },
  "dataSummary": {
    "filtered": "{filteredTotal} results of {total} {items}",
    "filteredSingle": "{filteredTotal} result of {total} {items}",
    "items": "items",
    "itemsSingle": "item",
    "selected": "{selected} selected",
    "total": "{total} {items}",
    "totalSingle": "{total} {items}"
  },
  "dataTableColumns": {
    "open": "Open column selector",
    "order": "Order columns",
    "select": "Select columns",
    "tip": "Manage columns"
  },
  "dataTableGroupBy": {
    "clear": "Clear group",
    "label": "Group by"
  },
  "dataView": {
    "label": "View"
  },
}

onView

Function that will be called when the user changes the view. This includes, searching, filtering, sorting, and paging. It will be called with an object describing the current view. See the 'view' property for an example of the object. Callers can combine 'view' and 'onView' to use Data as a controlled component.

function

(view) => {}

properties

This describes the objects found in 'data', sort of a schema. Using this property allows the caller to specify how the label renders and which properties should be filterable, searchable, sortable, and badgeable (included in DataFilters badge count). By default properties will be filterable, searchable, sortable, and badgeable unless specified otherwise.

For numeric data, a 'min', 'max', and 'step' can be specified for the range.

object

{
  name: {
    label: 'Name',
    search: false,
  },
  country: {
    label: 'Country',
    options: ['US', 'UK', 'FR'],
    sort: false,
  },
  status: {
    label: 'Status',
    options: [ 
      {label: 'Visited', value: true}, 
      {label: 'Not visited', value: false}, 
    ],
    filter: false,
  },
  age: {
    { label: 'Age', badge: false },
    range: {
      min: 1,
      max: 120,
      step: 5
    },
  },
}

total

The total number of objects that exist in the data set BEFORE any filtering is applied. This should be used when retrieving data from a paged API where the number of objects in 'data' is only one page and the entire set of data is larger than a page or when the caller is managing filtering to indicate how large the data set is without any filters applied.

number

view

The current view of the data.

string

The name of the view in 'views' in use.

"flagged"

object

The view used to describe any filtering.

{
  properties: {
    country: ['US', 'UK'],
    age: {
      min: 22,
      max: 56,
    },
  },
  search: 'com',
  sort: {
    property: 'date',
    direction: 'desc',
  },
  page: 1,
  step: 50,
  columns: ['country']
}

views

The set of predefined views of the data.

array

[
  {
    name: 'English speaking',
    properties: {
      country: ['US', 'UK'],
    },
    search: 'comm',
    sort: {
      property: 'date',
      direction: 'desc',
    },
    step: 50
  },
  {
    name: 'middle age',
    properties: {
      age: {
        min: 40,
        max: 60,
      },
    },
    sort: {
      property: 'age',
      direction: 'asc',
    },
    step: 50
  },
]

React/DOM Properties

At its core, the Data component is a regular <div> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for div elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

data.button.kind

The kind of button to render for DataClearFilters, DataFilters, DataSearch, DataSort, and DataTableColumns. This can reference any button kinds defined in your button theme.

string

"toolbar"