Awesome Open Source
Awesome Open Source

Build Status npm version react-sync

A declarative approach to fetching API data using HTML5 Fetch


react-sync provides a single higher order component used for fetching data from your APIs

Rendering the data is your responsibility, but refreshing the data from the API is as simple as changing the parameters of your request. Let the component manage the state of fetching the data.

ReactSync Props

Name Description Type Required Default
url The url to fetch without any query parameters string Yes
headers Object containing all the headers to pass to the request object No null
params Object containing all the query parameters to pass to the request object No null
toQueryString Function used to convert the query parameters prop to a query string function No ./toQueryString.js
toData Function that takes a fetch response object and returns a promise that resolves to the data in the response function No returns response JSON by default
children Function that takes an object {promise, data, error} and returns a node to be rendered function Yes

Source: props.jsx

Child Props

The function passed to the children prop receives the fetch state

Name Description Type
promise The pending promise if any requests are outstanding instanceof Promise
data Data that has been fetched from the API result of toData
error Any fetch errors that may have occurred instanceof Error


npm install --save react-sync

Alternately this project builds to a UMD module named ReactSync, so you can include a unpkg script tag in your page

Look for window.ReactSync when importing the UMD module via a script tag


See the demo source for example usage with filtering

import React from 'react';
import ReactSync from 'react-sync';

const StarGazers = ({ owner, repo, githubToken }) => (
    headers={{Authorization: `token ${githubToken}`}}>
      ({ promise, data, error }) => (
          {promise !== null ? 'Loading...' : data}      


Composition is king when using this component.

For example, want to automatically refetch every minute? Create a component that wraps ReactSync and updates a timestamp query parameter every minute.

import React, { Component } from 'react';
import PropTypes from 'prop-types';
import Sync from 'react-sync';

const now = () => (new Date()).getTime();

export default class RefreshSync extends Component {
  static propTypes = {
    refreshEvery: PropTypes.number

  _timer = null;
  state = {
    _ts: now()

  triggerNextRefresh = after => {
    this._timer = setTimeout(this.refresh, after);

  refresh = () => {
    this.setState({ _ts: now() });

  componentDidMount() {

  componentWillReceiveProps({ refreshEvery }) {
    if (refreshEvery !== this.props.refreshEvery) {

  render() {
    const { params, } = this.props,
      { _ts } = this.state;

    return <Sync {} params={{ ...params, _ts }}/>;

What about attaching a token from the context to all requests?

import React, { Component } from 'react';
import PropTypes from 'prop-types';
import Sync from 'react-sync';

export default class AuthenticatedSync extends Component {
  static contextTypes = {
    token: PropTypes.string

  render() {
    const { headers, } = this.props,
      { token } = this.context;

    return (
          Authorization: token ? `Bearer ${token}` : null

How about just defaulting a base URL?

import React from 'react';
import Sync from 'react-sync';

export const MyApiSync = ({ path, }) => (
  <Sync {} url={[ '', path ].join('/')}/>
Alternatives To React Sync
Select To Compare

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Javascript (1,058,747
Reactjs (162,277
Promise (10,876
Fetch (8,850
Ajax (7,699
Higher Order Component (135