@media-sdk/native

React Native integration layer for @media-sdk/core. Provides a context provider and hooks for photo/video search, pagination, and client access in React Native applications.

This package is Expo-agnostic — it uses React hooks only (no react-native imports). Works in bare React Native CLI apps and Expo apps alike.

Installation

pnpm add @media-sdk/core @media-sdk/native react

Peer Dependencies

• React 18 or React 19

@media-sdk/core is installed automatically as a runtime dependency. No react-native peer dependency is required for the hooks package.

Provider

Create a PexelsMediaClient or PixabayMediaClient from core, then wrap your application with MediaProvider:

import { MediaProvider } from "@media-sdk/native";
import {
  ApiKeyProvider,
  PexelsMediaClient,
} from "@media-sdk/core";

const client = new PexelsMediaClient(
  new ApiKeyProvider(process.env.EXPO_PUBLIC_PEXELS_API_KEY!),
);

export function AppRoot({ children }: { children: React.ReactNode }) {
  return (
    <MediaProvider client={client}>
      {children}
    </MediaProvider>
  );
}

useMediaClient

Access the shared client from context. Must be called inside MediaProvider:

import { useMediaClient } from "@media-sdk/native";

function Example() {
  const client = useMediaClient();

  // client.searchPhotos(), client.getPhoto(), etc.
}

useMediaCapabilities

Read the active client's capabilities from context. Returns MediaCapabilities via getCapabilities(client):

import { useMediaCapabilities } from "@media-sdk/native";

function SearchTabs() {
  const caps = useMediaCapabilities();

  return (
    <>
      <Tab>Search</Tab>
      {caps.operations.curatedPhotos && <Tab>Curated</Tab>}
    </>
  );
}

Guard filter UI with caps.photoFilters / caps.videoFilters before passing values to search hooks.

useMediaSearch

Search photos with automatic fetching, pagination, and race protection:

import { useMediaSearch } from "@media-sdk/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>
      ))}
    </View>
  );
}

Options

{
  query: string;
  page?: number;      // initial page only (default: 1)
  perPage?: number;
  enabled?: boolean;  // default: true
  photoFilters?: PhotoSearchFilters;  // forwarded to searchPhotos unchanged
}

Result

{
  data: PaginatedResponse<Photo> | null;
  loading: boolean;
  error: Error | null;
  search: () => Promise<void>;
  nextPage: () => Promise<void>;
  previousPage: () => Promise<void>;
  refetch: () => Promise<void>;
}

useMediaVideos

Same contract as useMediaSearch, but for videos:

import { useMediaVideos } from "@media-sdk/native";

const {
  data,
  loading,
  error,
  nextPage,
  previousPage,
  refetch,
} = useMediaVideos({
  query: "nature",
  perPage: 20,
  videoFilters: {
    orientation: "landscape",
    size: "medium",
  },
});

Error Handling

Hooks surface errors from @media-sdk/core as native Error instances. Use isAbortError from core for custom searches:

import { isAbortError, MediaError } from "@media-sdk/core";

if (error instanceof MediaError) {
  if (error.code === "UNSUPPORTED_FILTER") {
    // handle unsupported filter
  }
}

if (isAbortError(error)) {
  // request was cancelled — hooks swallow aborts in UI state
}

Cancellation

Hooks abort in-flight requests when:

• A new search starts (query, page, filters, or perPage changes)
• refetch() is called while a request is active
• The component unmounts

Aborted requests are silently ignored: error stays null and stale responses cannot overwrite newer state.

Architecture

React Native Application
       │
       ▼
@media-sdk/native   ← Provider + hooks (React only)
       │
       ▼
@media-sdk/core    ← API client, cache, types
       │
       ▼
Pexels / Pixabay API

Pair with @media-sdk/ui-native (when available) for presentational components, or build your own UI with RN primitives.

Public API

import {
  MediaProvider,
  useMediaCapabilities,
  useMediaClient,
  useMediaSearch,
  useMediaVideos,
  type UseMediaSearchOptions,
  type UseMediaSearchResult,
  type UseMediaVideosOptions,
  type UseMediaVideosResult,
} from "@media-sdk/native";

Versioning

This package is at 0.1.0 — pre-1.0 API may evolve. See the monorepo CHANGELOG for release notes.