stac-react

React hooks to build front-end applications for STAC APIs.

Note: stac-react is in early development, the API will likely break in future versions.

Installation

With NPM:

npm i @developmentseed/stac-react

With Yarn:

yarn add @developmentseed/stac-react

Peer Dependency: @tanstack/react-query

stac-react relies on TanStack Query for data fetching and caching. To avoid duplicate React Query clients and potential version conflicts, stac-react lists @tanstack/react-query as a peer dependency. This means you must install it in your project:

npm install @tanstack/react-query
# or
yarn add @tanstack/react-query

If you do not install it, your package manager will warn you, and stac-react will not work correctly.

Getting started

stac-react's hooks must be used inside children of a React context that provides access to the stac-react's core functionality.

To get started, initialize StacApiProvider with the base URL of the STAC catalog. StacApiProvider automatically sets up a TanStack Query QueryClientProvider for you, so you do not need to wrap your app with QueryClientProvider yourself.

import { StacApiProvider } from 'stac-react';

function StacApp() {
  return (
    <StacApiProvider apiUrl="https://my-stac-api.com">{/* Other components */}</StacApiProvider>
  );
}

If you want to provide your own custom QueryClient (for advanced caching or devtools), you can pass it as a prop:

import { StacApiProvider } from 'stac-react';
import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      gcTime: 10 * 60 * 1000, // 10 minutes
    },
  },
});

function StacApp() {
  const isDevelopment = process.env.NODE_ENV === 'development';

  return (
    <StacApiProvider
      apiUrl="https://my-stac-api.com"
      queryClient={queryClient}
      enableDevTools={isDevelopment}
    >
      {/* Other components */}
    </StacApiProvider>
  );
}

For additional information, see the React Query setup guide: docs/react-query-setup.md.

Now you can start using stac-react hooks in child components of StacApiProvider

import { StacApiProvider, useCollections } from 'stac-react';

function Collections() {
  const { collections } = useCollections();

  return (
    <ul>
      {collections.collections.map(({ id, title }) => (
        <li key={id}>{title}</li>
      ))}
    </ul>
  );
}

function StacApp() {
  return (
    <StacApiProvider apiUrl="https://my-stac-api.com">
      <Collections />
    </StacApiProvider>
  );
}

API

StacApiProvider

Provides the React context required for stac-react hooks.

Initialization

import { StacApiProvider } from 'stac-react';

function StacApp() {
  return <StacApiProvider apiUrl="https://my-stac-api.com">// Other components</StacApiProvider>;
}

Component Properties

Option	Type	Description
apiUrl	string	The base URL of the STAC catalog.
queryClient	QueryClient	Optional. Custom TanStack Query QueryClient instance. If not provided, a default QueryClient will be created.
options	object	Optional. Configuration object for customizing STAC API requests (e.g., headers, authentication).
enableDevTools	boolean	Optional. Enables TanStack Query DevTools browser extension integration by exposing the QueryClient on window.__TANSTACK_QUERY_CLIENT__. Defaults to false. Recommended for development only.

useCollections

Retrieves collections from a STAC catalog.

Initialization

import { useCollections } from 'stac-react';
const { collections } = useCollections();

Return values

Option	Type	Description
collections	array	A list of collections available from the STAC catalog. Is null if collections have not been retrieved.
isLoading	boolean	true when the initial request is in progress. false once data is loaded or an error occurred.
isFetching	boolean	true when any request is in progress (including background refetches). false otherwise.
reload	function	Callback function to trigger a reload of collections.
error	Error	Error information if the last request was unsuccessful. undefined if the last request was successful.

Example

import { useCollections } from "stac-react";

function CollectionList() {
  const { collections, isLoading } = useCollections();

  if (isLoading) {
    return 

Loading collections...


  }

  return (
    <>
    {collections ? (
      <ul>
        {collections.collections.map(({ id, title }) => (
          <li key={id}>{title}</li>
        ))}
      </ul>
      <button type="button" onclick={reload}>Update collections</button>
    ): (


No collections


    )}
    </>
  );
}

useCollection

Retrieves a single collection from the STAC catalog.

Initialization

import { useCollection } from 'stac-react';
const { collection } = useCollection(id);

Parameters

Option	Type	Description
id	string	The collection ID.

Return values

Option	Type	Description
collection	object	The collection matching the provided ID. Is null if collection has not been retrieved.
isLoading	boolean	true when the initial request is in progress. false once data is loaded or an error occurred.
isFetching	boolean	true when any request is in progress (including background refetches). false otherwise.
reload	function	Callback function to trigger a reload of the collection.
error	Error	Error information if the last request was unsuccessful. undefined if the last request was successful.

Example

import { useCollection } from 'stac-react';

function Collection() {
  const { collection, isLoading } = useCollection('collection_id');

  if (isLoading) {
    return 

Loading collection...

;
  }

  return (
    <>
      {collection ? (
        <>
          <h2>{collection.id}</h2>


{collection.description}


        </>
      ) : (


Not found


      )}
    </>
  );
}

useItem

Retrieves an item from the STAC catalog. To retrieve an item, provide its full url to the useItem hook.

Initialization

import { useItem } from 'stac-react';
const { item } = useItem(url);

Parameters

Option	Type	Description
url	string	The URL of the item you want to retrieve.

Return values

Option	Type	Description
item	object	The item matching the provided URL.
isLoading	boolean	true when the initial request is in progress. false once data is loaded or an error occurred.
isFetching	boolean	true when any request is in progress (including background refetches). false otherwise.
reload	function	Callback function to trigger a reload of the item.
error	Error	Error information if the last request was unsuccessful. undefined if the last request was successful.

Examples

import { useItem } from 'stac-react';

function Item() {
  const { item, isLoading } = useItem('https://stac-catalog.com/items/abc123');

  if (isLoading) {
    return 

Loading item...

;
  }

  return (
    <>
      {item ? (
        <>
          <h2>{item.id}</h2>


{item.description}


        </>
      ) : (


Not found


      )}
    </>
  );
}

useStacSearch

Executes a search against a STAC API using the provided search parameters.

Initialization

import { useStacSearch } from 'stac-react';
const { results } = useStacSearch();

Return values

| Option | Type | Description | | ------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | | submit | function | Callback to submit the search using the current filter parameters. Excecutes an API call to the specified STAC API. | | ids | array<string> | List of item IDs to match in the search, undefined if unset. | | setIds(itemIds) | function | Callback to set ids. itemIds must be an array of string with the IDs of the selected items, or undefined to reset. | | bbox | array<number> | Array of coordinates [northWestLon, northWestLat, southEastLon, southEastLat], undefined if unset. | | setBbox(bbox) | function | Callback to set bbox. bbox must be an array of coordinates [northWestLon, northWestLat, southEastLon, southEastLat], or undefined to reset. | | collections | array<string> | List of select collection IDs included in the search query. undefined if unset. | | setCollections(collectionIDs) | function | Callback to set collections. collectionIDs must be an array of string with the IDs of the selected collections, or undefined to reset. | | dateRangeFrom | string | The from-date of the search query. undefined if unset. | | setDateRangeFrom(fromDate) | function | Callback to set dateRangeFrom. fromDate must be ISO representation of a date, ie. 2022-05-18, or undefined to reset. | | dateRangeTo | string | The to-date of the search query. undefined if unset.