Hydrogen React

Hydrogen React is an unopinionated and performant library of Shopify-specific React components, reusable functions, and utilities for interacting with the Storefront API. This guide provides a complete reference of the components, hooks, and utilities that Hydrogen React offers, and their relationships to each other.

Choose a version:

Anchor to setupSetup

Run one of the example commands to install the package
Import the component, hook, or utility that you want to use in your app. For more detailed instructions, see the Getting Started Guide.

Navigate toGetting Started Guide

Install the Hydrogen React package

npm i --save @shopify/hydrogen-react

Anchor to authenticationAuthentication

To use Hydrogen React, you need to authenticate with and make requests to the Storefront API. Refer to Get started with Hydrogen React for instructions on how to get an access token and set up the Storefront API client.

Navigate toEnable Storefront API Access

Anchor to versioningVersioning

Hydrogen React is tied to specific versions of the Storefront API. For example, if you're using Storefront API version 2023-01, then Hydrogen React versions 2023.1.x are fully compatible.

Caution

If the Storefront API version update includes breaking changes, then Hydrogen React includes breaking changes. Because the API version is updated every three months, breaking changes to Hydrogen React could occur every three months.

Learn more about API versioning.

Anchor to componentsComponents

A component encapsulates all of the business logic and data parsing/processing for the concept it represents and outputs limited, sensible markup. Components provide defaults, but allow customizations and provide no visual styles, other than those provided natively by the browser.

Component example

Component

import {ShopPayButton} from '@shopify/hydrogen-react';

export function MyProduct({variantId}) {

return <ShopPayButton variantIds={[variantId]} />;

}

Anchor to hooksHooks

Hooks are functions that provide reusable, business and/or stateful logic. These functions allow you to leverage the business logic and state management functions used in the components with more flexibility.

Hook example

Hook

import {useMoney} from '@shopify/hydrogen-react';

export function MyComponent({variant}) {

const {currencyCode, currencySymbol, amount} = useMoney(variant.pricev2);

return (

<div>

<strong>{currencyCode}</strong>

<span>{currencySymbol}</span>

<span>{amount}</span>

</div>

);

}

Examples

Hook example

Hook

import {useMoney} from '@shopify/hydrogen-react';

export function MyComponent({variant}) {
  const {currencyCode, currencySymbol, amount} = useMoney(variant.pricev2);

  return (
    <div>
      <strong>{currencyCode}</strong>
      <span>{currencySymbol}</span>
      <span>{amount}</span>
    </div>
  );
}

Anchor to utilitiesUtilities

Utilities are reusable functions for common data manipulations performed on Storefront API data.

Utility example

Utility

import {flattenConnection, MediaFile} from '@shopify/hydrogen-react';

export function Product({product}) {

const media = flattenConnection(product.media);

return (

{media.map((mediaFile) => {

return <MediaFile data={mediaFile} key={mediaFile.id} />;

})}

</>

);

}

Examples

Utility example

Utility

import {flattenConnection, MediaFile} from '@shopify/hydrogen-react';

export function Product({product}) {
  const media = flattenConnection(product.media);
  return (
    <>
      {media.map((mediaFile) => {
        return <MediaFile data={mediaFile} key={mediaFile.id} />;
      })}
    </>
  );
}