@hydrogen-ui/components

A comprehensive React component library designed specifically for building Shopify Hydrogen storefronts. Features design token integration, optimized performance, and complete TypeScript support.

Installation

npm install @hydrogen-ui/components @hydrogen-ui/core
# or
yarn add @hydrogen-ui/components @hydrogen-ui/core
# or
pnpm add @hydrogen-ui/components @hydrogen-ui/core

Quick Start

import { HydrogenUIProvider } from '@hydrogen-ui/core';
import { Button, ProductCard, Money } from '@hydrogen-ui/components';
import { dawn } from '@hydrogen-ui/themes';

function App() {
  return (
    <HydrogenUIProvider theme={dawn}>
      <Button variant="primary">Shop Now</Button>
      <ProductCard product={product} />
      <Money data={price} />
    </HydrogenUIProvider>
  );
}

Component Categories

Layout Components

Components for structuring your page layouts with consistent spacing and responsive behavior.

• Box - Foundational layout primitive
• Flex - Flexbox layout component
• Grid - CSS Grid layout with responsive columns
• Stack - Simplified vertical/horizontal stacking

Typography Components

Text and content display components with design token integration.

• Text - Core text component with extensive styling
• Heading - Semantic headings (h1-h6)
• Link - Styled anchor component
• Code - Code snippet display

Interactive Components

Form elements and interactive UI components.

• Button - Multi-variant button component
• Input - Text input field
• Select - Dropdown select
• Checkbox - Checkbox input
• Radio - Radio button input
• OptimisticInput - Optimistic UI updates

Commerce Components

Shopify-specific commerce components for product display and cart functionality.

• ProductCard - Product display card
• Money - Currency formatting
• AddToCartButton - Add to cart functionality
• VariantSelector - Product variant picker
• ProductPrice - Price display with ranges
• ProductImage - Optimized product images
• CartLineItem - Cart item display
• CartSummary - Cart totals
• CartForm - Cart mutation forms
• CollectionGrid - Product grid layout
• FilterDrawer - Filter UI drawer
• Pagination - Collection pagination

Media Components

Components for displaying images, videos, and other media.

• Image - Responsive image with CDN optimization
• Video - HTML5 video player
• ExternalVideo - YouTube/Vimeo embeds
• MediaFile - Generic media display
• ModelViewer - 3D model viewer

Analytics Components

Track user interactions and page views.

• Analytics.Provider - Analytics context
• Analytics.ProductView - Product tracking
• Analytics.CartView - Cart tracking
• Analytics.CollectionView - Collection tracking
• Analytics.SearchView - Search tracking

Utility Components

Additional utility components.

• Script - Safe script injection
• Seo - SEO meta tags
• ShopPayButton - Shop Pay checkout
• RichText - Rich content renderer

Component API Reference

Layout Components

Box

The foundational layout primitive that all other components build upon.

import { Box } from '@hydrogen-ui/components';

<Box
  as="section"
  padding="md"
  margin={{ top: 'lg', bottom: 'sm' }}
  backgroundColor="surface.secondary"
  borderRadius="md"
  boxShadow="sm"
>
  Content goes here
</Box>

Props:

• as - HTML element to render (default: 'div')
• padding - Token-based padding: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | object
• margin - Token-based margin: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | object
• display - CSS display property
• position - CSS position property
• backgroundColor - Token-based background color
• borderRadius - Token-based border radius
• boxShadow - Token-based box shadow
• className - Additional CSS classes
• style - Inline styles

Flex

Flexbox layout component for flexible layouts.

import { Flex } from '@hydrogen-ui/components';

<Flex
  direction="row"
  justify="space-between"
  align="center"
  gap="md"
  wrap
>
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Flex>

Props:

• All Box props
• direction - 'row' | 'column' | 'row-reverse' | 'column-reverse'
• wrap - boolean | 'wrap' | 'nowrap' | 'wrap-reverse'
• justify - 'start' | 'end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'
• align - 'start' | 'end' | 'center' | 'stretch' | 'baseline'
• gap - Token-based gap spacing
• inline - Use inline-flex

Grid

CSS Grid component with responsive column support.

import { Grid } from '@hydrogen-ui/components';

<Grid
  columns={{ mobile: 1, tablet: 2, desktop: 4 }}
  gap="lg"
  alignItems="start"
>
  <ProductCard />
  <ProductCard />
  <ProductCard />
  <ProductCard />
</Grid>

Props:

• All Box props
• columns - number | string | responsive object
• rows - number | string | responsive object
• gap - Token-based gap
• columnGap - Token-based column gap
• rowGap - Token-based row gap
• alignItems - Grid align items
• justifyItems - Grid justify items

Typography Components

Text

Core text component with extensive styling options.

import { Text } from '@hydrogen-ui/components';

<Text
  as="p"
  size="lg"
  weight="semibold"
  color="text.secondary"
  align="center"
  truncate
>
  This is styled text content
</Text>

Props:

• as - HTML element (default: 'span')
• size - 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'
• weight - 'light' | 'normal' | 'medium' | 'semibold' | 'bold'
• color - Token-based color
• align - 'left' | 'center' | 'right' | 'justify'
• truncate - boolean (adds text truncation)
• font - 'body' | 'heading' | 'mono'
• leading - Line height: 'tight' | 'normal' | 'relaxed'
• italic - boolean
• underline - boolean
• lineThrough - boolean
• uppercase - boolean
• capitalize - boolean

Heading

Semantic heading component with automatic sizing.

import { Heading } from '@hydrogen-ui/components';

<Heading as="h1" color="primary">
  Page Title
</Heading>

<Heading as="h3" size="xl" weight="medium">
  Custom sized heading
</Heading>

Props:

• All Text props
• as - 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' (required)
• Size automatically mapped from heading level

Interactive Components

Button

Versatile button component with multiple variants and states.

import { Button } from '@hydrogen-ui/components';

<Button 
  variant="primary"
  size="lg"
  leftIcon={<CartIcon />}
  loading={isLoading}
  fullWidth
  onClick={handleClick}
>
  Add to Cart
</Button>

Props:

• variant - 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger'
• size - 'sm' | 'md' | 'lg'
• leftIcon - ReactNode
• rightIcon - ReactNode
• loading - boolean (shows spinner)
• disabled - boolean
• fullWidth - boolean
• as - 'button' | 'a' (for links styled as buttons)
• type - 'button' | 'submit' | 'reset'

Commerce Components

ProductCard

Display product information in a card format.

import { ProductCard } from '@hydrogen-ui/components';

<ProductCard
  product={product}
  variant="compact"
  showVendor
  showCompareAt
  quickAdd
  aspectRatio="4/5"
  loading={false}
/>

Props:

• product - Shopify product object
• variant - 'default' | 'compact' | 'detailed'
• showVendor - boolean
• showCompareAt - boolean (show compare-at price)
• quickAdd - boolean (show quick add button)
• aspectRatio - Image aspect ratio (e.g., '1/1', '4/5', '16/9')
• loading - boolean (skeleton state)

Money

Format and display currency values.

import { Money } from '@hydrogen-ui/components';

<Money
  data={{
    amount: '29.99',
    currencyCode: 'USD'
  }}
  withoutCurrency={false}
  withoutTrailingZeros
/>

Props:

• data - Shopify MoneyV2 object
• as - Component wrapper element
• withoutCurrency - boolean
• withoutTrailingZeros - boolean
• locale - Locale string (default: 'en-US')
• currencyDisplay - 'symbol' | 'narrowSymbol' | 'code' | 'name'
• measurement - Unit of measurement (e.g., 'kg')
• measurementSeparator - Separator for measurement

AddToCartButton

Add products to cart with loading states.

import { AddToCartButton } from '@hydrogen-ui/components';

<AddToCartButton
  variantId="gid://shopify/ProductVariant/123"
  quantity={1}
  attributes={[
    { key: 'gift_message', value: 'Happy Birthday!' }
  ]}
  disabled={!availableForSale}
>
  Add to Cart
</AddToCartButton>

Props:

• variantId - Shopify variant GID (required)
• quantity - number (default: 1)
• attributes - Array of { key, value }
• sellingPlanId - Subscription selling plan ID
• disabled - boolean
• children - Button content

VariantSelector

Product variant selection UI.

import { VariantSelector } from '@hydrogen-ui/components';

<VariantSelector
  product={product}
  selectedOptions={[
    { name: 'Color', value: 'Black' },
    { name: 'Size', value: 'Medium' }
  ]}
  displayStyle="buttons"
  onSelectedOptionsChange={setSelectedOptions}
/>

Props:

• product - Shopify product with variants
• selectedOptions - Array of selected option values
• onSelectedOptionsChange - Callback for option changes
• displayStyle - 'buttons' | 'dropdown' | 'swatches'
• showAvailability - boolean
• showPriceDifference - boolean

Media Components

Image

Responsive image with Shopify CDN optimization.

import { Image } from '@hydrogen-ui/components';

<Image
  data={product.featuredImage}
  alt={product.title}
  aspectRatio="4/5"
  sizes="(min-width: 1024px) 33vw, (min-width: 768px) 50vw, 100vw"
  loading="lazy"
/>

Props:

• data - Shopify image object
• alt - Alt text (required)
• aspectRatio - Aspect ratio string
• crop - 'center' | 'top' | 'bottom' | 'left' | 'right'
• sizes - Responsive sizes string
• loading - 'lazy' | 'eager'
• width - Fixed width
• height - Fixed height

Analytics Components

Analytics.Provider

Wrap your app to enable analytics tracking.

import { Analytics } from '@hydrogen-ui/components';

<Analytics.Provider
  shopId="shop123"
  userId="user456"
  debug={true}
>
  <App />
</Analytics.Provider>

Analytics.ProductView

Track product page views.

<Analytics.ProductView
  product={product}
  customData={{ source: 'search' }}
/>

Hooks

useComponentTokens

Access component-specific design tokens.

import { useComponentTokens } from '@hydrogen-ui/components';

function CustomComponent() {
  const tokens = useComponentTokens('button');
  
  return (
    <button style={{ 
      padding: tokens.padding.md,
      borderRadius: tokens.radius.md 
    }}>
      Custom Button
    </button>
  );
}

Theming

All components integrate with the Hydrogen UI theme system:

import { HydrogenUIProvider } from '@hydrogen-ui/core';
import { myCustomTheme } from './themes';

<HydrogenUIProvider theme={myCustomTheme}>
  {/* All components will use custom theme */}
</HydrogenUIProvider>

TypeScript

Full TypeScript support with exported types:

import type { 
  ButtonProps, 
  ProductCardProps,
  MoneyV2 
} from '@hydrogen-ui/components';

const MyButton: React.FC<ButtonProps> = (props) => {
  // Full type safety
};

Accessibility

All components follow WAI-ARIA guidelines:

• Semantic HTML elements
• ARIA attributes where needed
• Keyboard navigation support
• Screen reader friendly
• Focus management

Performance

• Lazy loading for images and heavy components
• Optimized re-renders with React.memo
• Skeleton loading states
• Shopify CDN integration for images
• Tree-shakeable exports

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari 14+
• iOS Safari 14+
• Chrome for Android (latest)

Contributing

See Contributing Guide

License

MIT