Hydrogen components overview
Hydrogen contains a set of Shopify-specific commerce components that help accelerate your development process. This guide provides a complete reference of Hydrogen components.
Primitive components
Primitive components are the building blocks for different component types, including products, variants, and cart. Hydrogen includes the following primitive components:
| Component name | Component type | Description |
|---|---|---|
| ExternalVideo | Shared | Renders an embedded video for the Storefront API's ExternalVideo object. |
| Image | Shared | Renders an image for the Storefront API's Image object. |
| MediaFile | Shared | 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. |
| Metafield | Client | Renders the value of the Storefront API's Metafield object. |
| Model3D | Client | Renders a 3D model (with the model-viewer tag) for the Storefront API's Model3d object. |
| Money | Client | Renders a string of the Storefront API's MoneyV2 object. |
| RawHtml | Shared | Renders an HTML string as HTML DOM elements. |
| ShopPayButton | Client | Renders a button that redirects to the Shop Pay checkout. |
| UnitPrice | Client | Renders a string of a unit price. |
| Video | Shared | Renders a video for the Storefront API's Video object. |
Global components
ShopifyProvider is a global Hydrogen component that wraps your entire app. The ShopifyProvider component is a shared component, which means that it renders on both the server and the client.
Product and variant components
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:
| Component name | Component type | Description |
|---|---|---|
| ProductDescription Alias: Product.Description |
Client | Renders a RawHtml component with the product's descriptionHtml. |
| ProductMetafield | Client | Renders a Metafield component with a product metafield. |
| ProductPrice Alias: Product.Price |
Client | Renders a Money component with the product priceRange's maxVariantPrice or minVariantPrice, or the product compareAtPriceRange's maxVariantPrice or minVariantPrice. |
| ProductProvider Alias: Product |
Client | Sets up a context with product details. |
| ProductTitle Alias: Product.Title |
Client | Renders a span element with the product's title. |
| SelectedVariantAddToCartButton Alias: Product.SelectedVariant.AddToCartButton |
Client | Renders an AddToCartButton component for the product's selected variant. |
| SelectedVariantBuyNowButton Alias: Product.SelectedVariant.BuyNowButton |
Client | Renders a BuyNowButton component for the product's selected variant. |
| SelectedVariantImage Alias: Product.SelectedVariant.Image |
Client | Renders an Image component for the product's selected variant's image. |
| SelectedVariantMetafield | Client | Renders a Metafield component for the product's selected variant's metafield. |
| SelectedVariantPrice Alias: Product.SelectedVariant.Price |
Client | Renders a Money component for the product's selected variant regular or compare at price. |
| SelectedVariantShopPayButton Alias: Product.SelectedVariant.ShopPayButton |
Client | Renders a ShopPayButton component for the product's selected variant. |
| SelectedVariantUnitPrice Alias: Product.SelectedVariant.UnitPrice |
Client | Renders a UnitPrice component for the product's selected variant's unit price. |
Cart components
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:
| Component name | Component type | Description |
|---|---|---|
| AddToCartButton | Client | Renders a button that adds an item to the cart when pressed. |
| BuyNowButton | Shared | Renders a button that adds an item to the cart and redirects the customer to checkout. |
| CartCheckoutButton | Client | Renders a button that redirects to the checkout URL for the cart. |
| CartEstimatedCost | Client | Renders a Money component for various amount types related to cart. |
| CartLineAttributes Alias: CartLine.Attributes |
Client | Takes a function as a child and calls that function for each of the cart line's attributes. |
| CartLineImage Alias: CartLine.Image |
Client | Renders an Image component for the cart line merchandise's image. |
| CartLinePrice Alias: CartLine.Price |
Client | Renders a Money component for the cart line merchandise's price or compare at price. |
| CartLineProductTitle Alias: CartLine.ProductTitle |
Client | Renders a span element (or the type of HTML element specified by the as prop) with the cart line merchandise's title. |
| CartLineProvider Alias: CartLine |
Client | Creates a context for using a cart line. |
| CartLineQuantity Alias: CartLine.Quantity |
Client | Renders a span element (or the type of HTML element specified by the as prop) with the cart line's quantity. |
| CartLineQuantityAdjustButton Alias: CartLine.QuantityAdjust |
Shared | Renders a button that adjusts the cart line's quantity when pressed. |
| CartLines | Shared | Iterates over each cart line and renders its children within a CartLineProvider for each cart line. |
| CartLineSelectedOptions Alias: CartLine.SelectedOptions |
Client | Takes a function as a child and calls that function for each of the cart line merchandise's selected options. |
| CartProvider | Client | Creates a context for using a cart. |
| CartShopPayButton | Client | Renders a ShopPayButton for the items in the cart. |
Localization components
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 is a server component, which means that it renders on the server.
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.