Guide

Getting started

Render one real fxhash token in a React page.

Install

bash

pnpm add @whitehash/ui @whitehash/react

Before you start

This guide assumes React 18.3+. The first render needs no API key, backend, wallet connection, or fxhash dependency.

1. Add the provider

Mount WhitehashProvideronce near your app’s root. The defaults are ready for the first render; add configuration when you need to control a service.

tsx

"use client"
import { WhitehashProvider } from "@whitehash/ui"
import "@whitehash/ui/styles.css"

<WhitehashProvider>…</WhitehashProvider>

2. Render one artwork

Give useToken a chain, contract, and token ID, then pass the normalized token to Artwork. The component coordinates the preview, seeded live iframe, play state, and unrevealed state.

tsx

import { useToken } from "@whitehash/react"
import { Artwork } from "@whitehash/ui"

function FirstArtwork() {
  const { token, loading, error } = useToken({
    chain: "tezos:mainnet",
    contract: "KT1KEa8z6vWXDJrVqtMrAeDVzsvxat3kHaCE",
    tokenId: "16333",
  })

  if (loading) return <p>Loading…</p>
  if (error || !token) return <p>{error ?? "Token not found"}</p>

  return (
    <Artwork.Root token={token}>
      <Artwork.Image />
      <Artwork.Live />
      <Artwork.PlayButton />
      <Artwork.StatusBadge />
    </Artwork.Root>
  )
}

The result

The image appears first. Run live swaps in the correctly seeded artwork inside a restricted iframe. If the token is unrevealed or needs onchfs before it can run, the component says so instead of failing silently.

3. Use the identity you already have

useToken is the direct path. If your application starts with a collector or project, discovery APIs return the same token shape:

You have	Use
A collector address	`useWalletTokens(address)`
A project	`useProject({ chain, id }).tokens`
Exact token identity	`useToken({ chain, contract, tokenId })`

Refs are optional serialized values for routes and paste fields. Normal reads use the identity fields already present on projects and tokens.

What the component handles

text

WhitehashToken
  → resolve the preview through ordered IPFS gateways
  → build the seeded live-artifact URL
  → preserve fx(params) and gentk-v1 seed quirks
  → sandbox the executable iframe
  → expose unrevealed and onchfs states

The read path does not depend on a hosted service. Continue to understand how it works, or inspect the complete Artwork anatomy.