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.
Framework components and hooks
Anchor link to section titled "Framework components and hooks"Framework components and hooks are available as part of the Hydrogen framework.
| Component name | Description | Related hooks |
|---|---|---|
| Cookie | Helps you build your own custom cookie and session implementations. | useSession |
| CookieSessionStorage | The default session storage mechanism for Hydrogen. | useSession |
| FileRoutes | Builds a set of default Hydrogen routes based on the output provided by Vite's import.meta.globEager method. |
Not applicable |
| FileSessionStorage | Persists session data to the file system. | useSession |
| Link | Used to navigate between routes. | useNavigate |
| MemorySessionStorage | Stores session data within Hydrogen runtime memory. | useSession |
| Route | Used to set up a route in Hydrogen that's independent of the file system. | Not applicable |
| Router | Provides the context for routing in your Hydrogen app. | Not applicable |
Primitive components and hooks
Anchor link to section titled "Primitive components and hooks"Primitive components and hooks are the building blocks for different component types, including products, variants, and cart.
| 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 ModelViewer depending on the mediaContentType of the media provided as a prop. |
Not applicable |
| ModelViewer | 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 according to the defaultLocale in the hydrogen.config.js file. |
useMoney |
| Metafield | Renders the value of the Storefront API's Metafield object. | Not applicable |
| Seo | Renders SEO information on a webpage. | 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
Anchor link to section titled "Global components and hooks"Global components wrap around your entire app. Hydrogen includes the ShopifyProvider component. The ShopifyProvider component relates to the following hooks that are used to fetch data from server components:
| Hook name | Description |
|---|---|
| fetchSync | Makes API requests and is the recommended way to make simple fetch calls on the server and on the client. |
| useQuery | Executes an asynchronous operation like fetch in a way that supports Suspense. |
| useServerProps | Manages server props passed to your server components when using Hydrogen as a React Server Component framework. |
| useShop | Accesses values within the shopify property in the hydrogen.config.js file. |
| useShopQuery | Makes server-only GraphQL queries to the Storefront API. |
| useUrl | Retrieves the current URL in a server or client component. |
Product and variant components and hooks
Anchor link to section titled "Product and variant components and hooks"Product and variant components and hooks relate to 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.
| Component name | Description | Related hooks |
|---|---|---|
| ProductDescription | Renders a div 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 |
Cart components and hooks
Anchor link to section titled "Cart components and hooks"Cart components and hooks relate to the merchandise that a customer intends to purchase.
| 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. | useCart |
| CartEstimatedCost | Renders a Money component for various amount types related to cart. |
useCart |
| 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 |
| CartProvider | Creates a context for using a cart. | useCart |
| CartShopPayButton | Renders a ShopPayButton for the items in the cart. |
Not applicable |
Localization components and hooks
Anchor link to section titled "Localization components and hooks"Localization components and hooks relate to creating shopping experiences for a global audience in local languages and currencies. Hydrogen includes a LocalizationProvider component.
The LocalizationProvider component relates to the following localization hooks:
| Hook name | Description |
|---|---|
| useCountry | Returns a tuple of the current localization country and a function for updating it. |
Metafield components and hooks
Anchor link to section titled "Metafield components and hooks"Metafield components and hooks relate to attaching specialized information to Shopify resources, such as part numbers or release dates.
| Name | Description |
|---|---|
| Metafield | Renders the value of the Metafield object. |
| useParsedMetafields | Returns an array of parsed metafields. |
Hydrogen includes the following utilities to help speed up your development process:
| Utility name | Description |
|---|---|
| flattenConnection | Transforms a connection object into a flat array. |
| isClient | Indicates if the code executed on the client. |
| isServer | Indicates if the code executed on the server. |
| log | Logs debugging, warning, and error information about the application. |
| parseMetafieldValue | Parses a metafield's value from a string to a sensible type corresponding to the metafield's type. |
| queryShop | Helps you query the Storefront API. |