Using Hydrogen components, hooks, and utilities

Hydrogen contains a set of Shopify-specific commerce components, hooks, and utilities that help accelerate your development process. This guide describes how Hydrogen components, hooks, and utilities work. It also provides information on integrating with other React frameworks, like Next.js or Gatsby.


A diagram that highlight Hydrogen components in association with Hydrogen hooks and utilities

Hydrogen components are objects that contain all of business logic for the commerce concept they represent. When rendered by default, without any class names or styles, Hydrogen components only take on the styles provided natively by the browser.

Hydrogen components are used to parse and process data, and render sensible defaults for semantic markup and localization. They don't include hardcoded content, such as Add to cart and Remove from cart strings.

Many Hydrogen components have GraphQL fragments that you can use to query the data you need. For example, the Image component includes an ImageFragment, which queries the id, url, and altText on the Storefront API Image object.

For a complete reference of Hydrogen components, refer to Hydrogen components overview.

Passthrough and render props

You can customize Hydrogen components using passthrough and render props. Using passthrough props, you can pass attributes as props to the Hydrogen component, and the Hydrogen component will pass them through to the rendered HTML tag. Using render props, you can pass a function that returns JSX as a child to the Hydrogen component.

Image component example

The Image component by default takes a single prop, image, which corresponds to the Storefront API Image object. It outputs an image tag with the src and alt attributes taken from the image url and image altText:

Any attributes supported by the component's outputted HTML tag are supported, except for those explicitly controlled by the component. For example, the src attribute for the Image component and the dangerouslySetInnerHtml attribute for the RawHtml component are explicitly controlled by the component.

If you wanted to include a class name and an onClick function, then you could use the className and onClick props:

RawHtml component example

You might want to customize the HTML tag that is outputted. For example, the RawHtml component takes a string of HTML and renders a div by default with its inner HTML set.

If you wanted to render the div as a section instead, then you could pass the HTML tag section through as the as prop:


A diagram that highlight Hydrogen hooks in association with Hydrogen components and utilities

Hydrogen hooks are functions that allow you to use state and other methods inside Hydrogen components.

Some examples of hooks used by components include the following:

  • The useProduct hook allows you to access product information in any components that are children of the Product component.
  • Cart hooks provide access to the cart object, and can be used by children components of the CartProvider.

For a complete reference of Hydrogen hooks, refer to Hydrogen hooks overview.


A diagram that highlight Hydrogen utilities in association with Hydrogen components and hooks

Hydrogen utilities are functions that are used to perform different tasks, and are intended to help you develop quickly.

For example, the flattenConnection utility takes Shopify storefront relay data (such as MediaConnections, VariantConnections, or MetafieldConnections), and transforms it into a flat array of objects.

For a complete reference of Hydrogen utilities, refer to Hydrogen utilities overview.

Integrating with other React frameworks

The majority of Hydrogen components, hooks, and utilities accept data from the Storefront API and render just like regular React components. This means you can use Hydrogen components, hooks, and utilities in other React frameworks like Next.js or Gatsby.

Shopify hasn't optimized integrating with other frameworks for the developer preview, so you need to follow some special instructions to make it work. While the instructions in this section are specific Next.js, you can follow a similar pattern to support other frameworks.

Getting started with Next.js

  1. In your Next.js app, install Hydrogen, react-router-dom, and next-transpile-modules:

  2. Instruct Next.js to compile @shopify/hydrogen from ESM (ES Modules) to CJS (CommonJS) by editing your next.config.js file:

Fetching data in Next.js

Shopify recommends calling the Storefront API on the server. Hydrogen will soon introduce a mechanism to make server-to-server calls without exhausting rate limits, so it's best to structure your apps this way from the start.

The following example shows the general structure of a product page in Next.js:


The following limitations apply when using Hydrogen components, hooks, and utilities in Next.js.

You can't use useShopQuery in Next.js

You can't use useShopQuery in Next.js because it's a hook that is meant to be run in Hydrogen's server components. Since the stable version of Next.js doesn't allow you to render a component only on the server, you need to fetch data in a getStaticProps or getServerSideProps function instead.

Shopify recommends writing a utility like getShopifyData({query, variables}), which takes your Storefront API credentials and makes a GraphQL query. You can then use this in the Next.js functions.

You can't use server components in Next.js

Hydrogen is currently using a modified version of server components which supports context and SSR (server-side rendering). This isn't yet supported in the version of server components that Next.js uses.

If you want to use the Alpha version of server components in Next.js, then you need to wrap any Hydrogen component that use Context in *.client.js components. This is the only way to currently use context in Next.js server components.

Next steps