Skip to main content

useActiveSponsorAds

Overview​

useActiveSponsorAds is a React hook for fetching currently active sponsor ads intended for public display. It queries the public /api/sponsor-ads endpoint and returns sponsor ad records paired with their associated item data. This hook is designed for use on homepage layouts, item detail sidebars, and other public-facing components that show sponsored content.

The file also exports activeSponsorAdsQueryKeys for external cache management.

Source: template/hooks/use-active-sponsor-ads.ts

Signature​

function useActiveSponsorAds(options?: UseActiveSponsorAdsOptions): UseActiveSponsorAdsReturn

Parameters​

UseActiveSponsorAdsOptions​

PropertyTypeDefaultDescription
limitnumber10Maximum number of active sponsor ads to fetch
enabledbooleantrueWhether the query should execute automatically

Return Values​

UseActiveSponsorAdsReturn​

PropertyTypeDescription
sponsorsSponsorWithItem[]Array of active sponsor ads with their item data
isLoadingbooleantrue during the initial fetch
isErrorbooleantrue if the query failed
errorError | nullThe error object, if the query failed
refetch() => voidManually trigger a refetch of active sponsor ads

SponsorWithItem​

interface SponsorWithItem {
  sponsor: SponsorAd;
  item: ItemData | null;
}

Each entry pairs the sponsor ad database record (SponsorAd) with the associated item data (ItemData). The item field may be null if the referenced item no longer exists.

Exported Query Keys​

export const activeSponsorAdsQueryKeys = {
  all: ['active-sponsor-ads'] as const,
  list: (limit: number) => [...activeSponsorAdsQueryKeys.all, 'list', limit] as const,
};

Implementation Details​

  • Public endpoint: Uses fetch directly against GET /api/sponsor-ads (not the authenticated serverClient), making it suitable for client-side rendering without authentication.
  • Cache configuration: staleTime of 5 minutes and gcTime of 10 minutes. refetchOnWindowFocus is disabled since sponsor ads do not change frequently.
  • Limit parameter: The limit is passed as a URL search parameter to control how many ads are returned.
  • Default empty array: When no data is available, sponsors defaults to an empty array rather than undefined.

Usage Examples​

Homepage sponsor ads section​

import { useActiveSponsorAds } from '@/hooks/use-active-sponsor-ads';

function SponsorAdsSection() {
  const { sponsors, isLoading, isError } = useActiveSponsorAds({ limit: 5 });

  if (isLoading) return <div>Loading sponsors...</div>;
  if (isError || sponsors.length === 0) return null;

  return (
    <section className="sponsor-ads">
      <h3>Sponsored</h3>
      <div className="sponsor-grid">
        {sponsors.map(({ sponsor, item }) => (
          <a key={sponsor.id} href={`/items/${sponsor.itemSlug}`}>
            {item?.icon_url && <img src={item.icon_url} alt={sponsor.itemName} />}
            <span>{sponsor.itemName}</span>
          </a>
        ))}
      </div>
    </section>
  );
}
import { useActiveSponsorAds } from '@/hooks/use-active-sponsor-ads';

function ItemDetailSidebar({ showSponsors }: { showSponsors: boolean }) {
  const { sponsors, isLoading } = useActiveSponsorAds({
    limit: 3,
    enabled: showSponsors,
  });

  if (!showSponsors || isLoading) return null;

  return (
    <aside>
      <h4>Sponsored Items</h4>
      {sponsors.map(({ sponsor, item }) => (
        <div key={sponsor.id}>
          <strong>{sponsor.itemName}</strong>
          {item && <p>{item.description}</p>}
        </div>
      ))}
    </aside>
  );
}

Invalidating the cache after admin changes​

import { useQueryClient } from '@tanstack/react-query';
import { activeSponsorAdsQueryKeys } from '@/hooks/use-active-sponsor-ads';

function useRefreshPublicSponsors() {
  const queryClient = useQueryClient();

  return () => {
    queryClient.invalidateQueries({
      queryKey: activeSponsorAdsQueryKeys.all,
    });
  };
}