@developmentseed/stac-react

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

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.

import { StacApiProvider } from "stac-react";

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

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 />
    </StacApiProvide>
  );
}

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
    </StacApiProvide>
  );
}

Component Properties

Option	Type	Description
apiUrl.	string	The base url of the STAC catalog.

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.
state	str	The status of the request. "IDLE" before and after the request is sent or received. "LOADING" when the request is in progress.
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, state } = useCollections();

  if (state === "LOADING") {
    return <p>Loading collections...</p>
  }

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

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.
state	str	The status of the request. "IDLE" before and after the request is sent or received. "LOADING" when the request is in progress.
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, state } = useCollection("collection_id");

  if (state === "LOADING") {
    return <p>Loading collection...</p>
  }

  return (
    <>
    {collection ? (
      <>
        <h2>{collection.id}</h2>
        <p>{collection.description}</p>
      </>
    ) : (
      <p>Not found</p>
    )}
    </>
  );
}

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.
state	str	The status of the request. "IDLE" before and after the request is sent or received. "LOADING" when the request is in progress.
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, state } = useItem("https://stac-catalog.com/items/abc123");

  if (state === "LOADING") {
    return <p>Loading item...</p>
  }

  return (
    <>
    {item ? (
      <>
        <h2>{item.id}</h2>
        <p>{items.description}</p>
      </>
    ) : (
      <p>Not found</p>
    )}
    </>
  );
}

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.
setDateRangeTo(toDate)	function	Callback to set dateRangeto. toDate must be ISO representation of a date, ie. 2022-05-18, or undefined to reset.
sortby	array	Specifies the order of results. Array of `{ field: string, direction: 'asc'
setSortby(sort)	function	Callback to set sortby. sort must be an array of `{ field: string, direction: 'asc'
limit	number	The number of results returned per result page.
setLimit(limit)	function	Callback to set limit. limit must be a number, or undefined to reset.
results	object	The result of the last search query; a GeoJSON FeatureCollection with additional members. undefined if the search request has not been submitted, or if there was an error.
state	string	The status of the request. "IDLE" before and after the request is sent or received. "LOADING" when the request is in progress.
error	Error	Error information if the last request was unsuccessful. undefined if the last request was successful.
nextPage	function	Callback function to load the next page of results. Is undefined if the last page is the currently loaded.
previousPage	function	Callback function to load the previous page of results. Is undefined if the first page is the currently loaded.

Examples

Render results

import { useStacSearch } from "stac-react";

function StacComponent() {
  const { result } = useStacSearch();

  return (
    <>
      <div class="item-list">
        {results && (
          <ul>
            {results.features.map(({ id }) => (
              <li key={id}>{ id }</li>
            ))}
          </ul>
        )}
      </div>
    </>
  )
}

Handle errors

import { useCallback } from "react";
import { useStacSearch } from "stac-react";

import Map from "./map";

function StacComponent() {
  const { error, result } = useStacSearch();

  return (
    <>
      <div class="item-list">
        {error && <p>{ error.detail }</p>}
        {results && (
          <ul>
            {results.features.map(({ id }) => (
              <li key={id}>{ id }</li>
            ))}
          </ul>
        )}
      </div>
    </>
  )
}

Pagination

import { useStacSearch } from "stac-react";

function StacComponent() {
  const {
    nextPage,
    previousPage,
    result
  } = useStacSearch();

  return (
    <>
      <div class="item-list">
        {results && (
          // render results
        )}
      </div>
      <div class="pagination">
        <button type="button" disabled={!previousPage} onClick={previousPage}>
        <button type="button" disabled={!nextPage} onClick={nextPage}>
      </div>
    </>
  )
}

Set collections

import { useStacSearch } from "stac-react";

function StacComponent() {
  const { collections } = useCollections();
  const { collections: selectedCollections, setCollections, results, submit } = useStacSearch();

  const handleChange = useCallback((event) => {
    const { value } = event.target;

    const nextValues = selectedCollections.includes(value)
      ? selectedCollections.filter((v) => v !== value)
      : [ ...selectedCollections, value ];

    setCollections(nextValues);
  }, [selectedCollections, setCollections]);

  return (
    <>
      <div class="query-builder">
        <form onSubmit={submit}>
          <fieldset>
            <legend>Select collections</legend>
            {collections.map(({ id, title }) => (
              <input 
                id={id}
                name="collections"
                value={id}
                type="checkbox"
                onChange={handleChange}
                checked={selectedCollections.includes(id)}
              />
              <label htmlFor={id}>{title}</label>
            ))}
          <fieldset>
          <button type="submit">Search</button>
        </form>
      </div>
    </>
  )
}

Set bounding box

import { useCallback } from "react";
import { useStacSearch } from "stac-react";

function StacComponent() {
  const { bbox, setBbox, submit } = useStacSearch();

  const handleDrawComplete = useCallback((feature) => {
    setIsBboxDrawEnabled(false);
    
    const { coordinates } = feature.geometry;
    const bbox = [...coordinates[0][0], ...coordinates[0][2]];
    setBbox(bbox);
  }, [setBbox]);

  <Map handleDrawComplete={handleDrawComplete} />
}

This example assumes that a Map component handles drawing and calls handleDrawComplete to set the bbox for the search. handleDrawComplete is called with a GeoJSON feature representing the bounding box drawn on the map.

Set date range

import { useStacSearch } from "stac-react";

function StacComponent() {
  const {
    dateRangeFrom,
    setDateRangeFrom,
    dateRangeTo,
    setDateRangeTo,
    submit
  } = useStacSearch();

  return (
    <>
      <input type="date" name="date_from" onChange={setDateRangeFrom} value={dateRangeFrom} />
      <input type="date" name="date_to" onChange={setDateRangeTo} value={dateRangeTo} />
      <button type="button" onclick={submit}>
    </>
  )
}

Types

Error

{
  detail: "Invalid bbox object"
  status: 400,
  statusText: "Bad Request"
}

Option	Type	Description
detail	string	`object
status	number	HTTP status code of the response.
statusText	string	Status text for the response.

Development

Run tests

yarn test

Lint

yarn lint

Build

yarn build