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
- Get started with Hydrogen and begin building a custom storefront.
- Learn about Hydrogen's architecture and framework.
- Learn about React Server Components, an opinionated data-fetching and rendering workflow for React apps.