useCampaigns

Hook for fetching all the valid campaigns that have been created on Metrom. Supports optional filtering.

Import


import { useCampaigns } from "@metrom-xyz/react";

Usage


import { useCampaigns, CampaignType } from "@metrom-xyz/react";
 
function App() {
  const { isLoading, data } = useCampaigns({
    page: 1,
    pageSize: 10,
    type: CampaignType.Rewards,
  });
 
  if (isLoading) return <div>loading...</div>;
 
  if (!data) return <div>no campaigns</div>;
 
  return (
    <div>
      {data.campaigns.map((campaign) => (
        <div key={campaign.id}>
          <p>{campaign.chainId}</p>
          <p>{campaign.from}</p>
          <p>{campaign.to}</p>
        </div>
      ))}
    </div>
  );
}

Parameters


import { type UseCampaignsParams } from "@metrom-xyz/react";

page, pageSize

number

Required campaigns pagination information.


import { useCampaigns, CampaignStatus } from "@metrom-xyz/react";
 
function App() {
  const { isLoading, data } = useCampaigns({
    page: 1,
    pageSize: 10,
  });
}

type

CampaignType

Required campaigns type to filter for. Metrom currently supports rewards and points campaigns.


import { useCampaigns, CampaignType } from "@metrom-xyz/react";
 
function App() {
  const { isLoading, data } = useCampaigns({
    page: 1,
    pageSize: 10,
    type: CampaignType.Rewards,
  });
}

chainIds

number[] | undefined

Optional campaign chain ids to filter for; the chain id is where the campaign lives in. Defaults to undefined.


import { useCampaigns } from "@metrom-xyz/react";
 
function App() {
  const { isLoading, data } = useCampaigns({
    page: 1,
    pageSize: 10,
    type: CampaignType.Rewards,
    chainIds: [1],
  });
}

chainTypes

ChainType[] | undefined

Optional chain types to filter for; the chain type is where the campaign lives in. Defaults to undefined.


import { useCampaigns, ChainType } from "@metrom-xyz/react";
 
function App() {
  const { isLoading, data } = useCampaigns({
    page: 1,
    pageSize: 10,
    type: CampaignType.Rewards,
    chainTypes: [ChainType.Evm],
  });
}

protocols

SupportedProtocol[] | undefined

Optional protocols to filter for; the protocol is the one targeted by the campaign. Defaults to undefined. Protocols can be any of the supported types SupportedDex | SupportedLiquityV2 | SupportedAaveV3 | SupportedBridge | SupportedGmxV1.


import { useCampaigns, SupportedDex } from "@metrom-xyz/react";
 
function App() {
  const { isLoading, data } = useCampaigns({
    page: 1,
    pageSize: 10,
    type: CampaignType.Rewards,
    protocols: [SupportedDex.UniswapV3],
  });
}

statuses

CampaignStatus[] | undefined

Optional statues to filter for. Defaults to undefined.


import { useCampaigns, CampaignStatus } from "@metrom-xyz/react";
 
function App() {
  const { isLoading, data } = useCampaigns({
    page: 1,
    pageSize: 10,
    type: CampaignType.Rewards,
    statuses: [CampaignStatus.Active, CampaignStatus.Upcoming],
  });
}

orderBy

CampaignOrderBy | undefined

An optional field that specifies how to sort the results; sorting by CampaignOrderBy.Apr is supported only for rewards campaigns. Defaults undefined.


import { useCampaigns, CampaignOrderBy } from "@metrom-xyz/react";
 
function App() {
  const { isLoading, data } = useCampaigns({
    page: 1,
    pageSize: 10,
    type: CampaignType.Rewards,
    orderBy: CampaignOrderBy.Apr,
  });
}

asc

boolean | undefined

An optional field that specifies the sort direction of the results; Defaults undefined.


import { useCampaigns } from "@metrom-xyz/react";
 
function App() {
  const { isLoading, data } = useCampaigns({
    page: 1,
    pageSize: 10,
    type: CampaignType.Rewards,
    orderBy: CampaignOrderBy.Apr,
    asc: false,
  });
}

options

TanStack Query parameters. See the TanStack Query query docs for more info.

Metrom React library does not support all TanStack Query parameters, like queryFn and queryKey, are used internally and cannot be overriden. Check out the source to see what parameters are not supported.

Return Type


import { type UseCampaignsReturnValue } from "@metrom-xyz/react";

data

PaginatedCampaigns | undefined


interface PaginatedCampaigns {
  totalItems: number;
  campaigns: Campaign[];
}

Paginated list of fetched campaigns, and the total items count. Defaults to undefiend.

isPending

boolean

Is true whenever there’s no cached data and no query attempt was finished yet.

isLoading

boolean

Is true whenever the first fetch for a query is in-flight.

isFetching

boolean

Is true whenever the queryFn is executing, which includes initial pending as well as background refetches.