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

Pixel Foxes

png

1611d956...b9fa_0

Crypto Adventure

webp

87459ead...5dba_0

TestyPepes

png

0d2b4300...6746_0

Aym the GM

png

8664fcbc...dc19_0

SNOW

jpeg

3265e1cf...34b2_0

The Pepeverse

jpeg

94f664c1...bc6e_0

"use client"

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

const MOCK_ORDINALS: OrdinalOutput[] = [
  {
    outpoint:
      "1611d956f397caa80b56bc148b4bce87b54f39b234aeca4668b4d5a7785eb9fa_0",
    contentType: "image/png",
    name: "Pixel Foxes",
    origin:
      "1611d956f397caa80b56bc148b4bce87b54f39b234aeca4668b4d5a7785eb9fa_0",
    satoshis: 1,
    tags: ["type:image/png", "name:Pixel Foxes"],
  },
  {
    outpoint:
      "87459ead23591c06e2e06de62051e2265c6697dad8647d0aaba4933265ad5dba_0",
    contentType: "image/webp",
    name: "Crypto Adventure",
    origin:
      "87459ead23591c06e2e06de62051e2265c6697dad8647d0aaba4933265ad5dba_0",
    satoshis: 1,
    tags: ["type:image/webp", "name:Crypto Adventure"],
  },
  {
    outpoint:
      "0d2b430030ab8480a430a300e0393d107b3754bce4d98bf919c39f0e752b6746_0",
    contentType: "image/png",
    name: "TestyPepes",
    origin:
      "0d2b430030ab8480a430a300e0393d107b3754bce4d98bf919c39f0e752b6746_0",
    satoshis: 1,
    tags: ["type:image/png", "name:TestyPepes"],
  },
  {
    outpoint:
      "8664fcbca0d1b6c6e2323b42434d90b57be562b6c49bc1f266a7fa23bb8edc19_0",
    contentType: "image/png",
    name: "Aym the GM",
    origin:
      "8664fcbca0d1b6c6e2323b42434d90b57be562b6c49bc1f266a7fa23bb8edc19_0",
    satoshis: 1,
    tags: ["type:image/png", "name:Aym the GM"],
  },
  {
    outpoint:
      "3265e1cfee59754a6e9e3e473fc8dbbf7bf0ebb7a50d97d00c0870fb27b934b2_0",
    contentType: "image/jpeg",
    name: "SNOW",
    origin:
      "3265e1cfee59754a6e9e3e473fc8dbbf7bf0ebb7a50d97d00c0870fb27b934b2_0",
    satoshis: 1,
    tags: ["type:image/jpeg", "name:SNOW"],
  },
  {
    outpoint:
      "94f664c15f3f8a5f2930a053381b4b94e264c77434cd99b49b03734f7862bc6e_0",
    contentType: "image/jpeg",
    name: "The Pepeverse",
    origin:
      "94f664c15f3f8a5f2930a053381b4b94e264c77434cd99b49b03734f7862bc6e_0",
    satoshis: 1,
    tags: ["type:image/jpeg", "name:The Pepeverse"],
  },
]

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