snowcone docs

Product Image

Display product mockups with custom artwork rendered in real-time.

Interactive Demo

ProductImage is an optional React convenience over the mockup URL. Nothing here is required to render — it just renders the URL for you.

Try the interactive playground below - select different artworks and see the product mockup update in real-time:

Loading playground...

ProductImage Props

artworkstring
Simplest option: Single image URL applied to all placements.
Example: artwork="https://example.com/design.jpg"
Perfect for quick demos and when you don’t need placement-specific control.
placementsRecord<string, string>
Simple multi-placement: Map placement names to colors or image URLs.
Example: { Front: '#FF0000', Back: 'https://image.jpg' }
Note: For interactive artwork selection, use ArtSelector component instead.
imagesDesignElement[]
Advanced multi-placement: Array of design elements.
Example: [{ placement: 'Front', imageUrl: '/logo.png' }]
variantIdstring
Product variant ID. Auto-resolved from Product context if not provided.
mockupIdstring
Mockup view ID. Auto-resolved from Product context if not provided.
widthnumber
Image resolution in pixels. Default: 1400. Higher = better quality, slower load.
effects{ grain?: 1 | 2 }
Visual effects: {{ grain: 1 }}
ar'16:9' | '2:3'
Aspect ratio for mockup cropping.
16:9 - Landscape (default, no cropping)
2:3 - Portrait (ideal for cards and mobile)

Example: ar="2:3"
classNamestring
CSS classes: “w-full rounded-lg”

Product Props

productIdstringrequired
Product ID: “BEEB77”
productDataCatalogProduct
Optional pre-fetched data. Skips fetching when provided. Useful for SSR.
childrenReactNoderequired
Components that use product context (ProductImage, ProductPrice, etc.).

Simple Artwork (Minimal Code)

The simplest way to display a product with artwork - just pass an image URL to the artwork prop. No ArtSelector needed, no array of artworks - the image automatically fills all placements on the product.

Loading playground...

Aspect Ratio (ar)

Control the aspect ratio of mockup images using the ar prop. This is useful when you need portrait-oriented images for product cards, mobile layouts, or social media.

Available Ratios

  • 16:9 - Landscape (default, no cropping)
  • 2:3 - Portrait (crops sides, ideal for cards)
ProductCard uses 2:3 by default. When using ProductCard, the mockup is automatically cropped to portrait orientation for optimal card layouts.
Loading playground...

Multi-Placement Products

Some products like baseball caps have multiple placements where you can apply different artwork and colors:

  • Image placements: Use images prop with [{ placement, imageUrl }]
  • Color placements: Use updateSelection({ Crown: '#ff0000' }) from useProduct()

Interactive playground - customize the baseball cap with different artworks and colors:

Loading playground...

Installation

npm install @snowcone-app/ui
Styling — your Tailwind v4 build compiles it. In your global stylesheet, add @import '@snowcone-app/ui/styles/globals.css' (brings in Tailwind, the theme tokens, and an @source for the package) plus an @source for your own code. In Next.js, also add transpilePackages: ['@snowcone-app/ui']. Add className="dark" on an ancestor for dark mode.