---
title: Hydrogen React
description: Hydrogen React is a performant, framework-agnostic library of React components, reusable functions, and utilities for interacting with Shopify’s [Storefront API](/docs/api/storefront). It’s bundled with [Hydrogen](/docs/api/hydrogen), but can be used by any React-based web app.
api_version: 2025-07
api_name: hydrogen-react
source_url:
  html: https://shopify.dev/docs/api/hydrogen-react
  md: https://shopify.dev/docs/api/hydrogen-react.md
---

# Hydrogen React

Hydrogen React is a performant, framework-agnostic library of React components, reusable functions, and utilities for interacting with Shopify’s [Storefront API](https://shopify.dev/docs/api/storefront). It’s bundled with [Hydrogen](https://shopify.dev/docs/api/hydrogen), but can be used by any React-based web app.

***

## Setup

1. Install Hydrogen React in your project with your preferred package manager.
2. Import components, hooks, or utilities that you want to use in your app. For more detailed instructions, see the Getting Started guide.

[Tutorial - Getting Started with Hydrogen React](https://shopify.dev/docs/custom-storefronts/hydrogen-react)

### Examples

* #### Install the Hydrogen React package

  ##### npm

  ```undefined
  npm i --save @shopify/hydrogen-react
  ```

  ##### yarn

  ```undefined
  yarn add @shopify/hydrogen-react
  ```

## Authentication

To use Hydrogen React, you need to authenticate with and make requests to the [Storefront API](https://shopify.dev/docs/api/storefront). Hydrogen React includes an [API client](https://shopify.dev/docs/api/hydrogen-react/2025-07/utilities/createstorefrontclient) to securely handle API queries and mutations.

You can create and manage Storefront API access tokens by installing the [Headless sales channel](https://apps.shopify.com/headless) on your store.

Apps have access to [two kinds of tokens](https://shopify.dev/docs/api/usage/authentication#access-tokens-for-the-storefront-api): a public API token, which can be used in client-side code, and a private API token, which should only be used in server-side contexts and never exposed publicly.

[Install - Headless sales channel](https://apps.shopify.com/headless)

### Examples

* #### Authenticate a Hydrogen app

  ##### client.js

  ```javascript
  import {createStorefrontClient} from '@shopify/hydrogen-react';

  export const client = createStorefrontClient({
    // load environment variables according to your framework and runtime
    storeDomain: process.env.PUBLIC_STORE_DOMAIN,
    publicStorefrontToken: process.env.PUBLIC_STOREFRONT_API_TOKEN,
  });
  ```

  ##### .env

  ```undefined
  # Replace with your own store domain and Storefront API token

  PUBLIC_STOREFRONT_API_TOKEN="public_token"
  PRIVATE_STOREFRONT_API_TOKEN="private_token"
  PUBLIC_STORE_DOMAIN="store_id.myshopify.com"
  ```

  ##### server-side-query.js

  ```javascript
  import {client} from './client.js';

  export async function getServerSideProps() {
    const response = await fetch(client.getStorefrontApiUrl(), {
      body: JSON.stringify({
        query: GRAPHQL_QUERY,
      }),
      // Generate the headers using the private token.
      headers: client.getPrivateTokenHeaders(),
      method: 'POST',
    });

    if (!response.ok) {
      throw new Error(response.statusText);
    }

    const json = await response.json();

    return {props: json};
  }

  const GRAPHQL_QUERY = `
    query {
      shop {
        name
      }
    }
  `;
  ```

## Versioning

Hydrogen React is tied to specific versions of the [Storefront API](https://shopify.dev/docs/api/storefront), which is versioned quarterly. For example, if you're using Storefront API version `2023-10`, then Hydrogen versions `2023.10.x` are fully compatible.

Caution

If a Storefront API version includes breaking changes, then the corresponding Hydrogen React version will include the same breaking changes.

[Learn more - Shopify API versioning](https://shopify.dev/docs/api/usage/versioning)

[Learn more - API release notes](https://shopify.dev/docs/api/release-notes)

## Components

Components include all the business logic and data parsing required to produce predictable markup for objects available through the Storefront API. Components provide defaults but can be customized. Hydrogen React components include no visual styles, other than the ones provided natively by browsers.

### Examples

* #### Component example

  ##### Component

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

  export function MyProduct({variantId}) {
    return <ShopPayButton variantIds={[variantId]} />;
  }
  ```

## Hooks

Hooks are functions that provide reusable business and/or state logic. They give you additional flexibility to control the behavior and display of Hydrogen React components.

### Examples

* #### Hook example

  ##### Hook

  ```javascript
  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>
    );
  }
  ```

## Utilities

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

### Examples

* #### Utility example

  ##### Utility

  ```javascript
  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} />;
        })}
      </>
    );
  }
  ```

## How Hydrogen React works with Hydrogen

Hydrogen React is bundled as part of Hydrogen, Shopify’s opinionated headless commerce stack built on [Remix](https://remix.run). Hydrogen React is also published separately as a standalone package so that it can be used by other React-based frameworks.

Hydrogen adds features like standard routes, caching strategies, redirects, and SEO. When using Hydrogen, you can also install the Hydrogen sales channel, which includes built-in support for Oxygen, Shopify’s global edge hosting platform. Consider which approach works best for your use case and existing technology stack.

[Learn more - Hydrogen](https://shopify.dev/docs/custom-storefronts/hydrogen)

[Install - Hydrogen sales channel](https://apps.shopify.com/hydrogen)

## Resources

[Custom storefronts on Shopify\
\
Learn more about how to design, build, and manage custom storefronts on Shopify.](https://shopify.dev/custom-storefronts)

[Hydrogen on GitHub\
\
Follow the Hydrogen project, file bugs and feature requests, preview upcoming features, and more.](https://github.com/Shopify/hydrogen)