npm package: @hydrogen-ui/components
Description: React components for Hydrogen UI
Latest version: 0.1.0

# @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

```bash
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

```tsx
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](#box) - Foundational layout primitive
- [Flex](#flex) - Flexbox layout component  
- [Grid](#grid) - CSS Grid layout with responsive columns
- [Stack](#stack) - Simplified vertical/horizontal stacking

### Typography Components

Text and content display components with design token integration.

- [Text](#text) - Core text component with extensive styling
- [Heading](#heading) - Semantic headings (h1-h6)
- [Link](#link) - Styled anchor component
- [Code](#code) - Code snippet display

### Interactive Components

Form elements and interactive UI components.

- [Button](#button) - Multi-variant button component
- [Input](#input) - Text input field
- [Select](#select) - Dropdown select
- [Checkbox](#checkbox) - Checkbox input
- [Radio](#radio) - Radio button input
- [OptimisticInput](#optimisticinput) - Optimistic UI updates

### Commerce Components

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

- [ProductCard](#productcard) - Product display card
- [Money](#money) - Currency formatting
- [AddToCartButton](#addtocartbutton) - Add to cart functionality
- [VariantSelector](#variantselector) - Product variant picker
- [ProductPrice](#productprice) - Price display with ranges
- [ProductImage](#productimage) - Optimized product images
- [CartLineItem](#cartlineitem) - Cart item display
- [CartSummary](#cartsummary) - Cart totals
- [CartForm](#cartform) - Cart mutation forms
- [CollectionGrid](#collectiongrid) - Product grid layout
- [FilterDrawer](#filterdrawer) - Filter UI drawer
- [Pagination](#pagination) - Collection pagination

### Media Components

Components for displaying images, videos, and other media.

- [Image](#image) - Responsive image with CDN optimization
- [Video](#video) - HTML5 video player
- [ExternalVideo](#externalvideo) - YouTube/Vimeo embeds
- [MediaFile](#mediafile) - Generic media display
- [ModelViewer](#modelviewer) - 3D model viewer

### Analytics Components

Track user interactions and page views.

- [Analytics.Provider](#analyticsprovider) - Analytics context
- [Analytics.ProductView](#analyticsproductview) - Product tracking
- [Analytics.CartView](#analyticscartview) - Cart tracking
- [Analytics.CollectionView](#analyticscollectionview) - Collection tracking
- [Analytics.SearchView](#analyticssearchview) - Search tracking

### Utility Components

Additional utility components.

- [Script](#script) - Safe script injection
- [Seo](#seo) - SEO meta tags
- [ShopPayButton](#shoppaybutton) - Shop Pay checkout
- [RichText](#richtext) - Rich content renderer

## Component API Reference

### Layout Components

#### Box

The foundational layout primitive that all other components build upon.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

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

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

#### Analytics.ProductView

Track product page views.

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

## Hooks

### useComponentTokens

Access component-specific design tokens.

```tsx
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:

```tsx
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:

```tsx
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](../../CONTRIBUTING.md)

## License

MIT