ClayClay
  • Get Started
    • How to Use Clay
    • How to Read This Documentation
    • Composition Philosophy
    • Migrating From v2.x
    • Using Clay in JSPs
  • Components
    • Alert
    • Application Bar
    • Aspect Ratio
    • Autocomplete
    • Badge
    • Breadcrumb
    • Button Group
    • Buttons
    • Card
    • Chart
    • Color Picker
    • Data Provider
    • Date Picker
    • Drop Down
    • Empty State
    • Form
      • Checkbox
      • Dual List Box
      • Input
      • Radio Group
      • Select
      • Select Box
      • Toggle Switch
    • Forms Hierarchy
    • Heading
    • Icon
    • Label
    • Layout
    • Link
    • List
    • Loading Indicator
    • Localized Input
    • Management Toolbar
    • Menubar (Vertical Navigation)
    • Modal
    • Multi Select
    • Multi Step Nav
    • Nav
    • Navigation Bar
    • OverlayMask
    • Pagination
    • Pagination Bar
    • Panel
    • Popover
    • Progress Bar
    • Provider
    • Sidebar
    • Slider
    • Sticker
    • Table
    • Tabs
    • Text
    • Timelines
    • Time Picker
    • Toolbar
    • Tooltip
    • TreeView
    • Upper Toolbar
    • VerticalBar
  • Contributing
  • CSS Framework
    • Paver
    • SCSS
    • Color
    • Grid
    • Content
      • Typography
      • C Kbd
    • Utilities
      • Autofit
      • C Focus Inset
      • C Inner
      • C Spacing Utilities
      • Inline Item
      • Text
    • Playground
  • Examples
  • Docs
  • Sass API
  • Blog
  • Storybook
  • Codesandbox
  • Github
  • Use this menu to toggle between Atlas and Base Themes.

Data Provider

yarn add @clayui/data-provider

Simple but very powerful client, it was designed to help you consume data easily.

Stable3.58.0View in LexiconCHANGELOGstorybook demos

  • Introduction
  • Getting started
    • useResource hook
  • Features
    • Retry
    • Network Status
    • Variables change
    • Caching data
    • Data Fetching
      • Fetch
  • Advanced
    • Avoiding thundering herd problem
    • Caching data at root level
  • API
    • DataProvider

Introduction

ClayDataProvider gives functionality of data caching, attempts, polling, network status and avoiding the thundering herd problem. It is simple and powerful because:

  • Easy adoption, you can incrementally use in your application and both useResource hook and ClayDataProvider component and have all the functionality available.
  • Simple to start, use the basics you already know or take advantage of the full set of features to get the most out of it.
  • Built for data to reflect what users are doing in your application, it works perfectly for cases where data changes according to user interaction.
  • Extensible, enjoy the single cache in only one source of truth and save data between navigations to be used in future interactions.

Getting started

To consume data, you can work with two different ways in React, using the <ClayDataProvider /> component or useResource hook. We recommend that you use useResource for cases where your component has more logic to handle data, so it decreases the complexity and eliminates logic within JSX, use <ClayDataProvider /> for simpler cases that do not have so much logic involved in the data or when you are not familiar with hooks.

Copied!
Code Sample (expand to see it)

useResource hook

The vast majority of APIs are the same between useResource and <ClayDataProvider />, the difference is that there is no notifyOnNetworkStatusChange API in useResource, you control them via the OnNetworkStatusChange parameter when you need it.

Copied!
Code Sample (expand to see it)

Features

Retry

Make attempts on a request several times when a network or server error occurs.

fetchRetry is easy to set up and is enabled by default with the jitter setting for delays between attempts by default.

WarningThe values ​​contained in the code below are the default value.
Copied!
Code Sample (expand to see it)

Network Status

The DataProvider provides network status information for you if you want to create customizations in those statuses. If you are using <ClayDataProvider /> you can enable this information by activating the notifyOnNetworkStatusChangeAPI prop, once activated it will cause new renderings each time the network status changes.

Copied!
Code Sample (expand to see it)

Using network status with hooks is another option, it does not provide an abstraction for loading, error and networkStatus and all information is collected through the onNetworkStatusChange callback.

  • loading is equivalent to networkStatus < 4
  • error is equivalent to status === 5
Copied!
Code Sample (expand to see it)

Variables change

variables is an API for GET requests that help satisfy whether your cache will be retrieved from storage or not, this can be useful for cases where your data is formed by user interactions such as Autocomplete, you can still set a delay on the fetchDelay prop to ensure that your requests are not called every time a change of input value occurs, for example.

Copied!
Code Sample (expand to see it)

Caching data

You can cache your requests so that in new user interactions a new request is no longer necessary, by default the cache is deactivated.

The cache is guided by a policy, use the fetchPolicy prop to enable and configure the cache according to your use case.

WarningThe cache is governed by the algorithm least recently used (LRU), you can set the amount of data that will be stored using the storageMaxSize API. Each new query is equivalent to 1 size.

Data Fetching

const {resource} = useResource({fetch, link});

This is an API that replaces the link behavior of receiving an async function, this did not allow us to validate the cache correctly because we do not have the URL view. This API is more friendly and has a unique responsibility, you may be able to pass an async function that accepts the link and options, and return the data. useResource will use its async function instead of the fetch default.

Fetch

import fetch from 'unfetch';

const App = () => {
	const {resource} = useResource({fetch, link: 'https://clay.dev'});
	// ...
};

Advanced

Avoiding thundering herd problem

Starting with delay.initial, the delay of each subsequent retry is increased exponentially, meaning it's multiplied by 2 each time. For example, if delay.initial is 100, additional retries will occur after delays of 200, 400, 800, etc.

With the jitter option enabled, delays are randomized anywhere between 0ms (instant), and 2x the configured delay. This way you get the same result on average, but with random delays.

These two features combined help alleviate the thundering herd problem, by distributing load during major outages. Without these strategies, when your server comes back up it will be hit by all of your clients at once, possibly causing it to go down again.

WarningThe implementation of this was based on the apollo-link-retry plugin for React Apollo.

Caching data at root level

The DataProvider can be used on small components that need some data and if it is very reused by the application in other pages, it does not make sense to consult this data every time the user interacts with it in other parts of your application, you can take advantage of the root level cache, ensuring that the next user interactions in the component are with data in the cache, even if it is on other pages.

Copied!
Code Sample (expand to see it)

API

DataProvider

PropertyTypeRequiredDefaultDescription
children
(props: IChildrenProps) => React.ReactElementtrueIt uses a render props pattern made popular by libraries like React Motion and React Router. Children as a function is required for the DataProvider to pass the props with data information, network status, refetch method and others. If this is an impediment try using the `useResource` hook.
notifyOnNetworkStatusChange
booleanfalsefalseSet to true means that network status information will be passed via `renders props` and will also cause new renderings as networkStatus changes, when false rendering does not happen again.

How can this be improved? Create an issue!