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 storefront. | Not applicable |
| ShopifyAnalytics | Sends commerce-related analytics to Shopify. | 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 |
| 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. Use the |
| 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 |
|---|---|---|
| ProductPrice | Renders a Money component with the product priceRange's maxVariantPrice or minVariantPrice, or the product compareAtPriceRange's maxVariantPrice or minVariantPrice. |
Not applicable |
| ProductOptionsProvider | Sets up a context with state that tracks the selected variant and options. | useProductOptions |
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 |
| CartCost | 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 hooks
Anchor link to section titled "Localization hooks"Localization hooks relate to creating shopping experiences for a global audience in local languages and currencies. The ShopifyProvider component provides localization data for the app.
The ShopifyProvider component relates to the following localization hooks:
| Hook name | Description |
|---|---|
| useLocalization | Returns the locale, country, and language of the current page. |
Metafield components
Anchor link to section titled "Metafield components"Metafield components 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. |
Hydrogen includes the following utilities to help speed up your development process:
| Utility name | Description |
|---|---|
| flattenConnection | Transforms a connection object into a flat array. |
| gql | Adds syntax highlighting to your GraphQL queries. |
| isBrowser | Indicates if the code executed in the browser. |
| isServer | Indicates if the code executed on the server. |
| log | Logs debugging, warning, and error information about the application. |
| parseMetafield | Creates a new metafield object with a value that has been parsed according to the metafield type. |
| 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 within Use the |