BigBlocks

Ordinals Grid

Responsive grid of owned ordinal NFTs with ORDFS thumbnails, fetched from the 1sat API or passed as pre-fetched data

6 Ordinals

Rare Pepe #42

png

a1b2c3d4...a1b2_0

1Sat Punk #1337

webp

b2c3d4e5...b2c3_0

Genesis Block Art

svg+xml

c3d4e5f6...c3d4_0

Unnamed

json

d4e5f6a1...d4e5_0

Sigma Identity Avatar

jpeg

e5f6a1b2...e5f6_0

On-Chain Note

plain

f6a1b2c3...f6a1_0

"use client"

import { useState } from "react"
import {
  OrdinalsGrid,
  type OrdinalOutput,
} from "@/registry/bigblocks/blocks/ordinals-grid"

const MOCK_ORDINALS: OrdinalOutput[] = [
  {
    outpoint:
      "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2_0",
    contentType: "image/png",
    name: "Rare Pepe #42",
    origin:
      "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2_0",
    satoshis: 1,
    tags: ["type:image/png", "name:Rare Pepe #42"],
  },
  {
    outpoint:
      "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3_0",
    contentType: "image/webp",
    name: "1Sat Punk #1337",
    origin:
      "b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3_0",
    satoshis: 1,
    tags: ["type:image/webp", "name:1Sat Punk #1337"],
  },
  {
    outpoint:
      "c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_0",
    contentType: "image/svg+xml",
    name: "Genesis Block Art",
    origin:
      "c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_0",
    satoshis: 1,
    tags: ["type:image/svg+xml", "name:Genesis Block Art"],
  },
  {
    outpoint:
      "d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5_0",
    contentType: "application/json",
    origin:
      "d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5_0",
    satoshis: 1,
    tags: ["type:application/json"],
  },
  {
    outpoint:
      "e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6_0",
    contentType: "image/jpeg",
    name: "Sigma Identity Avatar",
    origin:
      "e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6_0",
    satoshis: 1,
    tags: ["type:image/jpeg", "name:Sigma Identity Avatar"],
  },
  {
    outpoint:
      "f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1_0",
    contentType: "text/plain",
    name: "On-Chain Note",
    origin:
      "f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1_0",
    satoshis: 1,
    tags: ["type:text/plain", "name:On-Chain Note"],
  },
]

export function OrdinalsGridDemo() {
  const [selected, setSelected] = useState<OrdinalOutput | null>(null)

  return (
    <div className="space-y-4">
      <OrdinalsGrid
        ordinals={MOCK_ORDINALS}
        onSelect={setSelected}
      />
      {selected && (
        <div className="rounded-md border border-border bg-muted/50 p-3">
          <p className="text-sm">
            <span className="font-medium">Selected:</span>{" "}
            {selected.name ?? "Unnamed"}{" "}
            <span className="font-mono text-xs text-muted-foreground">
              ({selected.outpoint.slice(0, 12)}...)
            </span>
          </p>
        </div>
      )}
    </div>
  )
}

A responsive grid that displays owned ordinal NFTs. Supply an address to auto-fetch from the 1sat API over a streaming NDJSON response, or pass pre-fetched ordinals directly to skip the network call. Each card shows the inscription image, name, content type badge, and truncated outpoint. The underlying useOrdinalsGrid hook is also exported for headless usage.

Installation

bunx shadcn@latest add https://registry.bigblocks.dev/r/ordinals-grid.json

Usage

import { OrdinalsGrid, type OrdinalOutput } from "@/components/blocks/ordinals-grid"
 
// Fetch from a Bitcoin address
export function WalletOrdinals() {
  return (
    <OrdinalsGrid
      address="1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
      onSelect={(ordinal) => console.log("Selected:", ordinal.outpoint)}
      showCount
    />
  )
}
 
// Pass pre-fetched ordinals (e.g. from server-side fetch)
export function StaticOrdinals({ ordinals }: { ordinals: OrdinalOutput[] }) {
  return (
    <OrdinalsGrid
      ordinals={ordinals}
      onSelect={(ordinal) => router.push(`/ordinal/${ordinal.outpoint}`)}
      scrollable
      maxHeight="600px"
    />
  )
}

API Reference

OrdinalsGrid

Prop	Type	Default	Description
`address`	`string`	—	Bitcoin address to fetch ordinals for from the 1sat API. Mutually exclusive with `ordinals`.
`ordinals`	`OrdinalOutput[]`	—	Pre-fetched ordinals. When provided, no API fetch occurs.
`apiUrl`	`string`	`"https://api.1sat.app/1sat"`	Base URL for the 1sat owner API.
`limit`	`number`	—	Maximum number of items to display. No limit by default.
`onSelect`	`(ordinal: OrdinalOutput) => void`	—	Called when an ordinal card is clicked.
`showCount`	`boolean`	`true`	Whether to show a count header above the grid.
`scrollable`	`boolean`	`false`	Wrap the grid in a `ScrollArea`.
`maxHeight`	`string`	—	CSS max-height for the scroll area (requires `scrollable`).
`className`	`string`	—	Additional CSS classes applied to the outer container.

OrdinalOutput

interface OrdinalOutput {
  outpoint: string     // txid_vout or txid.vout format
  contentType: string  // MIME type (e.g. "image/png")
  name?: string        // Display name from MAP metadata
  origin: string       // Origin outpoint for ORDFS content resolution
  satoshis: number     // Satoshi value of the output
  tags: string[]       // Raw tags array from the wallet output
}

Hook

Use useOrdinalsGrid directly for custom grid layouts or to integrate ordinal fetching into an existing component.

import { useOrdinalsGrid } from "@/components/blocks/ordinals-grid"
 
function CustomOrdinalList({ address }) {
  const { items, isLoading, error, count, reload } = useOrdinalsGrid({ address })
 
  if (isLoading) return <p>Loading {address}...</p>
  if (error) return <p>Error: {error.message} <button onClick={reload}>Retry</button></p>
 
  return (
    <ul>
      {items.map((item) => (
        <li key={item.outpoint}>
          {item.name ?? item.outpoint} — {item.contentType}
        </li>
      ))}
    </ul>
  )
}

UseOrdinalsGridReturn

Property	Type	Description
`items`	`OrdinalOutput[]`	Parsed ordinal items ready for display, respecting `limit`.
`isLoading`	`boolean`	Whether the initial fetch is in progress. Always `false` when `ordinals` is provided.
`error`	`Error \| null`	Error from the fetch, or `null`. Always `null` when `ordinals` is provided.
`count`	`number`	Total number of items currently loaded.
`reload`	`() => void`	Re-fetch ordinals from the API. No-op when `ordinals` is provided.

Notes

The 1sat API streams results as NDJSON. The hook reads the response body as a stream, so large wallets begin rendering incrementally rather than waiting for the full response.
Requests are aborted when the component unmounts or when address changes, preventing stale state.
Outpoints are normalized to underscore format (txid_vout) internally for ORDFS compatibility.

OpNS Manager Post Button