​
Import

import { CollectibleCard } from "@0xsequence/marketplace-sdk/react";

​
Usage

​
Data Hooks

The SDK provides specialized hooks to fetch and format data for the CollectibleCard component:

​
Market Cards

import { useListMarketCardData } from "@0xsequence/marketplace-sdk/react";

const {
  collectibleCards,
  isLoading,
  hasNextPage,
  isFetchingNextPage,
  fetchNextPage,
} = useListMarketCardData({
  orderbookKind,
  collectionType,
  filterOptions,
  searchText,
  showListedOnly,
  collectionAddress,
  chainId,
});

​
Shop Cards

For shop cards, there are two hooks based on the contract type: 
// For ERC721 tokens
import { useList721ShopCardData } from "@0xsequence/marketplace-sdk/react";

const { collectibleCards, isLoading } = useList721ShopCardData({
  primarySaleItemsWithMetadata,
  chainId,
  contractAddress,
  salesContractAddress,
  enabled: contractType === ContractType.ERC721,
});

// For ERC1155 tokens
import { useList1155ShopCardData } from "@0xsequence/marketplace-sdk/react";

const { collectibleCards, isLoading } = useList1155ShopCardData({
  chainId,
  contractAddress,
  salesContractAddress,
  enabled: contractType === ContractType.ERC1155,
  primarySaleItemsWithMetadata,
});
These hooks handle:
  • Data fetching and formatting
  • Loading states
  • Pagination (for market cards)
  • Type-specific data requirements
  • Integration with filters and search

​
Examples

Example of using the CollectibleCard component in a marketplace context:
import { CollectibleCard } from "@0xsequence/marketplace-sdk/react";

export default function MarketExample() {
  return (
    <CollectibleCard
      collectibleId="1"
      chainId={1}
      collectionAddress="0x..."
      marketplaceType="market"
      collectible={{
        // collectible data
        tokenId: "1",
        metadata: {
          name: "My NFT",
          image: "https://example.com/nft.png"
        }
      }}
      onCollectibleClick={(tokenId) => {
        console.log(`Clicked collectible ${tokenId}`);
      }}
    />
  );
}

​
Parameters

The component accepts different props based on the marketplace type:

​
Base Props

These properties are shared by all card types: 
interface MarketplaceCardBaseProps {
  collectibleId: string;
  chainId: number;
  collectionAddress: Address;
  collectionType?: ContractType;
  assetSrcPrefixUrl?: string;
  cardLoading?: boolean;
  marketplaceType?: MarketplaceType;
  isTradable?: boolean;
}
ParameterTypeDescription
collectibleIdstringUnique identifier for the collectible
chainIdnumberThe blockchain network ID
collectionAddressAddressThe smart contract address of the collection
collectionTypeContractTypeOptional. The type of contract (ERC721 or ERC1155)
assetSrcPrefixUrlstringOptional URL prefix for asset sources
cardLoadingbooleanOptional flag to show loading state
marketplaceTypeMarketplaceTypeOptional. Type of marketplace (‘market’ or ‘shop’)
isTradablebooleanOptional flag indicating if the item can be traded

​
Shop Card Props

Additional properties for shop cards (marketplaceType="shop"): 
interface ShopCardSpecificProps {
  salesContractAddress: Address;
  tokenMetadata: TokenMetadata;
  salePrice?: {
    amount: string;
    currencyAddress: Address;
  };
  saleStartsAt?: string;
  saleEndsAt?: string;
  quantityDecimals?: number;
  quantityInitial?: string;
  quantityRemaining?: string;
  unlimitedSupply?: boolean;
}
ParameterTypeDescription
salesContractAddressAddressThe address of the sales contract
tokenMetadataTokenMetadataMetadata for the token including name, description, image
salePriceobjectOptional. Price information including amount and currency
saleStartsAtstringOptional. Sale start timestamp
saleEndsAtstringOptional. Sale end timestamp
quantityDecimalsnumberOptional. Number of decimals for quantity
quantityInitialstringOptional. Initial supply amount
quantityRemainingstringOptional. Remaining supply amount
unlimitedSupplybooleanOptional. Whether the supply is unlimited

​
Market Card Props

Additional properties for market cards (marketplaceType="market"): 
interface MarketCardSpecificProps {
  orderbookKind?: OrderbookKind;
  collectible?: CollectibleOrder;
  onCollectibleClick?: (tokenId: string) => void;
  onOfferClick?: (params: {
    order?: Order;
    e: React.MouseEvent<HTMLButtonElement>;
  }) => void;
  balance?: string;
  balanceIsLoading: boolean;
  onCannotPerformAction?: (action: CollectibleCardAction) => void;
  prioritizeOwnerActions?: boolean;
}
ParameterTypeDescription
orderbookKindOrderbookKindOptional. Type of orderbook
collectibleCollectibleOrderOptional. Collectible order information
onCollectibleClickfunctionOptional. Handler for collectible click events
onOfferClickfunctionOptional. Handler for offer click events
balancestringOptional. User’s balance of this collectible
balanceIsLoadingbooleanWhether the balance is currently loading
onCannotPerformActionfunctionOptional. Handler for unauthorized actions
prioritizeOwnerActionsbooleanOptional. Whether to prioritize owner actions in UI

​
Features

​
Card Variants

The component supports two main variants:
  1. Market Card: Used for displaying collectibles in a marketplace context with:
    • Current listing price
    • Highest offer indicator
    • Balance/ownership information
    • Buy/Offer actions
  2. Shop Card: Used for primary sales with:
    • Sale price
    • Supply information
    • Sale status
    • Purchase actions

​
Automatic Type Detection

The component automatically handles different token standards:
  • ERC-721 (Non-fungible tokens)
  • ERC-1155 (Semi-fungible tokens)

​
Loading States

Built-in loading states are provided: 
<CollectibleCard
  cardLoading={true}
  // ... other props
/>

​
Price Formatting

The component includes sophisticated price formatting with:
  • Currency symbol display
  • Overflow/underflow indicators
  • Support for various token decimals
  • “Free” indicator for zero prices

​
Integration Examples

​
Market Content Integration

Here’s a complete example of integrating the CollectibleCard in a marketplace context: 
import {
  CollectibleCard,
  useListMarketCardData,
} from "@0xsequence/marketplace-sdk/react";

export function MarketContent({
  collectionAddress,
  chainId,
  onCollectibleClick,
}) {
  const {
    collectibleCards,
    isLoading,
    hasNextPage,
    isFetchingNextPage,
    fetchNextPage,
  } = useListMarketCardData({
    orderbookKind,
    collectionType,
    filterOptions,
    searchText,
    showListedOnly,
    collectionAddress,
    chainId,
  });

  return (
    <div>
      {collectibleCards.map((card, index) => (
        <button
          key={index}
          onClick={() => onCollectibleClick(card.collectibleId)}
          className="w-full cursor-pointer"
        >
          <CollectibleCard {...card} />
        </button>
      ))}
    </div>
  );
}

​
Shop Content Integration

Example of integrating the CollectibleCard in a shop context with contract type handling: 
import {
  CollectibleCard,
  useList721ShopCardData,
  useList1155ShopCardData,
} from "@0xsequence/marketplace-sdk/react";

export function ShopContent({
  saleContractAddress,
  collectionAddress,
  chainId,
  onCollectibleClick,
}) {
  // Choose hook based on contract type
  const { collectibleCards, isLoading } =
    contractType === ContractType.ERC721
      ? useList721ShopCardData({
          primarySaleItemsWithMetadata,
          chainId,
          contractAddress: collectionAddress,
          salesContractAddress: saleContractAddress,
          enabled: true,
        })
      : useList1155ShopCardData({
          chainId,
          contractAddress: collectionAddress,
          salesContractAddress: saleContractAddress,
          enabled: true,
          primarySaleItemsWithMetadata,
        });

  return (
    <div>
      {collectibleCards.map((card, index) => (
        <button
          key={index}
          onClick={() => onCollectibleClick(card.collectibleId)}
          className="w-full cursor-pointer"
        >
          <CollectibleCard {...card} />
        </button>
      ))}
    </div>
  );
}

​
Notes

The MarketplaceCollectibleCard component is designed to handle various marketplace scenarios with:
  • Responsive layout
  • Loading states
  • Price formatting
  • Supply tracking
  • Action handling
  • Owner-specific features
  • Offer management
When using with ERC-1155 tokens, note that:
  • Balance is displayed as “Owned: X” format
  • Supply information is shown for shop items
  • Quantity tracking is supported

​
Best Practices

  1. Data Fetching
    • Use the appropriate data hook based on your context (market/shop) and contract type (ERC721/ERC1155)
    • Enable conditional fetching using the enabled prop when necessary
    • Handle loading states appropriately
  2. Event Handling
    • Implement click handlers for both the card and specific actions (buy, offer)
    • Use the onCannotPerformAction callback to handle unauthorized actions
  3. Display
    • Wrap cards in buttons for clickable behavior
    • Use appropriate className for layout and spacing
    • Consider implementing infinite scroll or pagination for large collections