DataView
What is this?
DataView containers allow merchants to view and control a set of items in one or more layout types.
Header
The DataViewHeader arranges all the components that control or changes the displayed data. These components can be buttons, search forms, pagination, menus, filters, and so on.
Loading...
Rendering Data
The useDataViewState keeps track of ready, loading, empty, error, and not-found states. It also has default illustrations for empty, error, and not-found so that you only need to handle the ready and loading states.
Loading...
With Skeleton
Example of a skeleton collection.
Loading...
Usage
import { DataView, DataViewHeader, useDataViewState } from '@vtex/admin-ui'
function Example() {
const state = useDataViewState()
return (
<DataView state={state}>
<DataViewHeader>
<Flex>
<Search />
<DataViewActions>{actions}</DataViewActions>
</Flex>
{filters}
</DataViewHeader>
{content}
</DataView>
)
}
Initial State
The useDataViewState handles the DataView behavior.
Loading...
All props of JSX div element.
| Name | Type | Description | Required | Default |
|---|---|---|---|---|
| state | DataViewState | DataView state | ✅ | - |
DataViewHeader props
All props of JSX div element.
DataViewActions props
All props of JSX div element.
useDataViewState params
The params configure the initial state. The default values represent the ready state.
| Name | Type | Description | Required | Default |
|---|---|---|---|---|
| loading | boolean | Whether it is loading | 🚫 | false |
| error | Object | Whether there is an error | 🚫 | null |
| empty | Object | Whether it is empty | 🚫 | null |
| notFound | Object | Whether it is not found | 🚫 | null |
useDataViewState return
| Name | Type | Description |
|---|---|---|
| status | ready, loading, error, not-found, or empty | Current view status |
| statusObject | { loading: boolean, empty: Object, notFound: Object, error: Object } | Detailed view status |
| setStatus | React.Dispatch<{type: status }> | Sets the view status |
Variants
When to include a Table or a Card grid?
More than one layout type can be included in a DataView, but the default layout should be the one that prioritizes the property that best identifies the item. When deciding which layouts to support, follow these recommendations:
- Include a List layout with a Table when there are important item properties that are textual and may need to be compared. For example, a list of products, promotions, or orders.
- Include a Grid layout with Cards when there are important item properties that are visual. For example, app logos in a list of apps or thumbnails in a media gallery.
What Buttons should be in the DataView header?
Include tertiary neutral Buttons in the DataView header for actions that are related to the items being shown but don't modify them. For example, Export or Import.
What to avoid:
What to avoid:
- Don't add primary or secondary actions, such as Create item.
- Don't add actions that are not directly related to the content being shown.
- Don't use Buttons to filter items or to toggle the visibility of filters.
When to include Search in a DataView?
Always, to make it easier for merchants to find the information they are looking for. Support at least searching for Name or ID. Read the Search documentation for more information.
When to include Pagination in a DataView?
When there are more than 10 entries in the Table. Read the Pagination documentation for more information.
When to include Filters in a DataView?
When there are predefined options for properties that can be chosen as criteria to filter items. Read the Filter documentation for more information.
Position
Where should a DataView be positioned in a page?
- Use the DataView directly in a Page or inside a Card or Modal.
- Fill the entire width of the container, but respect its horizontal margin.
- Read the Listing page Template documentation to learn more about how to position the DataView in a dedicated page.
Where should Pagination be positioned in a DataView?
Considering left-to-right interfaces, follow these recommendations:
What to avoid:
- Position the Pagination in the top right, directly above the content and filters.
- When the list has a vertical scroll, duplicate the Pagination after the content in the bottom right.
What to avoid:
- Don't position the Pagination in a different container than the DataView.
Where should actions be positioned in a DataView?
Considering left-to-right interfaces, follow these recommendations:
What to avoid:
- If there is no Pagination, actions should be aligned to the right in the header.
- If there is Pagination, actions should be to the left of Pagination, but both should be aligned to the right in the header.
What to avoid:
- Don't use too many actions in each row. Limit to a maximum of five.
Where should Filters be positioned in a DataView?
Considering left-to-right interfaces, follow these recommendations:
What to avoid:
- Position Filters directly above the content that will be filtered and below the Search.
- Align Filters to the left.
What to avoid:
- Avoid positioning the filters in a different container than the DataView.
Behavior
What should be the empty state in a Data View?
The Data View includes a default 'empty' state for when no items exist in a list. This scenario should be represented by the following characteristics:
- Hide elements that are unnecessary in this state such as the search field, any filters, and both pagination triggers.
- Replace the Table or any other container being used to display the items by the phrase No [entity name] yet and, when it is possible to create items, the Create [entity name] action. This content should be styled and positioned according to the implementation.
What to avoid:
- Don't use technical language or internal concepts in the empty state message.
- Don't distract users with unnecessary elements or actions.
What should be the no results state in a Data View?
The Data View includes a default 'no results' state for when the search works but there are no results matching the query. This scenario should be represented by the following characteristics:
- Keep the search field, any filters and buttons active and disable both pagination triggers.
- Replace the Table or any other container being used to display the items by the phrase No results found and the Try using different terms or filters instruction. This content should be styled and positioned according to the implementation.
What to avoid:
- Don't use technical language or internal concepts in the no results message.
- Don't distract users with unnecessary elements or actions.
What should be the error state in a Data View?
The Data View includes a default 'error' state for when an error prevents items from loading or the search from returning results. This scenario should be represented by the following characteristics:
- Keep the search field and any filters active and disable both pagination triggers. Disable other buttons if they are unable to be triggered in this state.
- Replace the Table or any other container being used to display the items by the default illustration, the phrase Something went wrong and the Try again action. This content should be styled and positioned according to the implementation.
What to avoid:
- Don't overload the user with too much information or too many options in the error state.
- Avoid making the error state too prominent, as it may be a rare scenario for the user to encounter.