Hydrogen components, hooks, and utilities overview

Hydrogen contains a set of Shopify-specific commerce components, hooks, and utilities that help accelerate your development process. This guide provides a complete reference of the components, hooks, and utilities that Hydrogen offers, and their relationships to each other.

Primitive components and hooks

Primitive components and hooks are the building blocks for different component types, including products, variants, and cart. Hydrogen includes the following primitive components and hooks:

Component name Description Related hooks
ExternalVideo Renders an embedded video for the Storefront API's ExternalVideo object. Not applicable
Image Renders an image for the Storefront API's Image object. Not applicable
MediaFile Renders the media for the Storefront API's Media object. It either renders an Image, a Video, an ExternalVideo, or a Model3D depending on the mediaContentType of the media provided as a prop. Not applicable
Model3D Renders a 3D model (with the model-viewer tag) for the Storefront API's Model3d object. Not applicable
Money Renders a string of the Storefront API's MoneyV2 object. useMoney
Metafield Renders the value of the Storefront API's Metafield object. Not applicable
RawHtml Renders an HTML string as HTML DOM elements. Not applicable
ShopPayButton Renders a button that redirects to the Shop Pay checkout. Not applicable
UnitPrice Renders a string of a unit price. useMoney
Video Renders a video for the Storefront API's Video object. Not applicable

Global components and hooks

ShopifyProvider is a global Hydrogen component that wraps your entire app. You should place it in your app's entry point component. For example, your app's entry point component might be <App>.

The ShopifyProvider component relates to the following global hooks that you can use to fetch data from server components:

Hook name Description
useQuery A wrapper around useQuery from react-query. It supports Suspense calls on the server and on the client.
useServerState Manage a server state when using Hydrogen as a React Server Component framework.
useShop Access values within shopify.config.js.
useShopQuery Make server-only GraphQL queries to the Storefront API.

Product and variant components and hooks

Products are the goods, digital downloads, services, and gift cards that a merchant sells. If a product has options, like size or color, then merchants can add a variant for each combination of options.

Each combination of option values for a product can be a variant for that product. For example, a t-shirt might be available for purchase in blue and green. The blue t-shirt and the green t-shirt are variants.

Hydrogen includes the following product and variant components and hooks:

Component name Description Related hooks
ProductDescription Renders a RawHtml component with the product's descriptionHtml. Not applicable
ProductMetafield Renders a Metafield component with a product metafield. Not applicable
ProductPrice Renders a Money component with the product priceRange's maxVariantPrice or minVariantPrice, or the product compareAtPriceRange's maxVariantPrice or minVariantPrice. Not applicable
ProductProvider Sets up a context with product details. useProduct
ProductTitle Renders a span element with the product's title. Not applicable
SelectedVariantAddToCartButton Renders an AddToCartButton component for the product's selected variant. useProductOptions
SelectedVariantBuyNowButton Renders a BuyNowButton component for the product's selected variant. Not applicable
SelectedVariantImage Renders an Image component for the product's selected variant's image. useProductOptions
SelectedVariantMetafield Renders a Metafield component for the product's selected variant's metafield. Not applicable
SelectedVariantPrice Renders a Money component for the product's selected variant regular or compare at price. useProductOptions
SelectedVariantShopPayButton Renders a ShopPayButton component for the product's selected variant. Not applicable
SelectedVariantUnitPrice Renders a UnitPrice component for the product's selected variant's unit price. useMoney

Cart components and hooks

A cart contains the merchandise that a customer intends to purchase and the estimated cost associated with the cart. When a customer is ready to purchase their items, they can proceed to checkout.

Hydrogen includes the following cart components and hooks:

Component name Description Related hooks
AddToCartButton Renders a button that adds an item to the cart when pressed. Not applicable
BuyNowButton Renders a button that adds an item to the cart and immediately redirects the buyer to checkout. Not applicable
CartCheckoutButton Renders a button that redirects to the checkout URL for the cart. useCartCheckoutUrl
CartEstimatedCost Renders a Money component for various amount types related to cart. useCart
CartLineAttributes Takes a function as a child and calls that function for each of the cart line's attributes. Not applicable
CartLineImage Renders an Image component for the cart line merchandise's image. Not applicable
CartLinePrice Renders a Money component for the cart line merchandise's regular or compare at price. Not applicable
CartLineProductTitle Renders a span element (or the type of HTML element specified by the as prop) with the cart line merchandise's title. Not applicable
CartLineProvider Creates a context for using a cart line. useCartLine
CartLineQuantity Renders a span element (or the type of HTML element specified by the as prop) with the cart line's quantity. Not applicable
CartLineQuantityAdjustButton Renders a button that adjusts the cart line's quantity when pressed. Not applicable
CartLines Iterates over each cart line and renders its children within a CartLineProvider for each cart line. useCartLine
CartLineSelectedOptions Takes a function as a child and calls that function for each of the cart line merchandise's selected options. Not applicable
CartProvider Creates a context for using a cart.
CartShopPayButton Renders a ShopPayButton for the items in the cart. Not applicable

Localization components and hooks

Localization can help merchants expand their business to a global audience by creating shopping experiences in local languages and currencies.

The LocalizationProvider component automatically queries the Storefront API's localization field for the ISO code, name of the country, and available countries, and keeps this information in a context.

The LocalizationProvider component relates to the following localization hooks:

Hook name Description
useAvailableCountries Returns an array of the available countries used for localization purposes.
useCountry Returns a tuple of the current localization country and a function for updating it.

Metafield components and hooks

Metafields allow you to attach specialized information to Shopify resources, such as part numbers or release dates. Merchants and other apps can retrieve and edit the data that's stored in metafields from the Shopify admin.

Hydrogen includes the following metafield components and hooks:

Name Description
Metafield Renders the value of the Metafield object.
useParsedMetafields Returns an array of parsed metafields.

Utilities

Hydrogen includes the following utilities to help speed up your development process:

Utility name Description
isClient Indicates if the code executed on the client.
isServer Indicates if the code executed on the server.
flattenConnection Transforms a connection object into a flat array.
parseMetafieldValue Parses a metafield's value from a string to a sensible type corresponding to the metafield's type.

Next steps

On this page