useMediaSearch

Search photos with automatic fetching, pagination, race protection, and abort handling. Reference for @media-sdk/native@^0.1.0.

pnpm add @media-sdk/core@^0.3.1 @media-sdk/native@^0.1.0 react

Must be called inside MediaProvider.

Options

Extends SearchParams from @media-sdk/core plus enabled:

Option	Type	Default	Description
query	string	—	Required. Search query. Empty or whitespace-only strings skip automatic requests
page	number	1	Initial page only — does not re-sync after mount
perPage	number	Provider default	Results per page
enabled	boolean	true	When false, skips automatic fetch on mount and when query changes
photoFilters	PhotoSearchFilters	—	Forwarded to client.searchPhotos unchanged

photoFilters are not stripped or validated by the hook. Unsupported filters throw MediaError with code: "UNSUPPORTED_FILTER" from core. Gate filter UI with useMediaCapabilities before passing values.

PhotoSearchFilters

interface PhotoSearchFilters {
  orientation?: "landscape" | "portrait" | "square";
  size?: "large" | "medium" | "small";
  color?: PhotoColor | PixabayColor;
  category?: string;
  minWidth?: number;
  minHeight?: number;
  editorsChoice?: boolean;
  locale?: string;
}

Returns

Field	Type	Description
data	PaginatedResponse<Photo> | null	Search results, or null before the first successful response
loading	boolean	true while a request is in flight
error	Error | null	Last non-abort error. Aborted requests do not set error
search	() => Promise<void>	Manually trigger a search (respects in-flight deduplication)
nextPage	() => Promise<void>	Navigate to the next page when data.pagination.hasNext is true
previousPage	() => Promise<void>	Navigate to the previous page when data.pagination.hasPrevious is true
refetch	() => Promise<void>	Re-run search for the current page, bypassing in-flight deduplication

Type export

import type {
  UseMediaSearchOptions,
  UseMediaSearchResult,
} from "@media-sdk/native";

Example

import { useMediaSearch } from "@media-sdk/native";
import { Pressable, Text, View } from "react-native";

function PhotoSearch({ query }: { query: string }) {
  const {
    data,
    loading,
    error,
    nextPage,
    previousPage,
    refetch,
  } = useMediaSearch({
    query,
    page: 1,
    perPage: 20,
    enabled: true,
  });

  if (loading) return <Text>Loading…</Text>;
  if (error) return <Text>{error.message}</Text>;

  return (
    <View>
      {data?.items.map((photo) => (
        <Text key={photo.id}>{photo.photographer}</Text>
      ))}
      <Pressable
        onPress={() => void previousPage()}
        disabled={!data?.pagination.hasPrevious}
      >
        <Text>Previous</Text>
      </Pressable>
      <Pressable
        onPress={() => void nextPage()}
        disabled={!data?.pagination.hasNext}
      >
        <Text>Next</Text>
      </Pressable>
      <Pressable onPress={() => void refetch()}>
        <Text>Refetch</Text>
      </Pressable>
    </View>
  );
}

Filter forwarding

import { useMediaCapabilities, useMediaSearch } from "@media-sdk/native";
import { Text } from "react-native";

function FilteredSearch({ query }: { query: string }) {
  const caps = useMediaCapabilities();

  const { data, loading } = useMediaSearch({
    query,
    photoFilters: {
      ...(caps.photoFilters.orientation
        ? { orientation: "landscape" as const }
        : {}),
      ...(caps.photoFilters.color
        ? { color: "blue" as const }
        : {}),
    },
  });

  if (loading) return <Text>Loading…</Text>;
  return <Text>{data?.items.length ?? 0} results</Text>;
}

Changing photoFilters triggers a new search (same as query or page changes).

enabled

Defer fetching until the user submits a search:

import { useState } from "react";
import { useMediaSearch } from "@media-sdk/native";
import { SearchBar } from "@media-sdk/ui-native";

function DeferredSearch() {
  const [query, setQuery] = useState("");
  const [submittedQuery, setSubmittedQuery] = useState("");

  const { data, loading } = useMediaSearch({
    query: submittedQuery,
    enabled: submittedQuery.length > 0,
  });

  return (
    <>
      <SearchBar
        value={query}
        onChange={setQuery}
        onSubmit={() => setSubmittedQuery(query)}
      />
      {loading && <Text>Loading…</Text>}
      {data && <Text>{data.items.length} results</Text>}
    </>
  );
}

Cancellation

Hooks manage AbortController internally. Prior requests abort when query, page, or filters change, or on unmount. Aborted errors are swallowed — see Cancellation and Error handling recipes.

Related

• useMediaVideos — same contract for videos
• Pagination — nextPage / previousPage behavior
• Filters — capability-gated filter UI