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' | 'desc' } setSortby(sort) | function | Callback to set sortby. sort must be an array of { field: string, direction: 'asc' | 'desc' }, or undefined to reset. 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 | The error return from the API. Either a stringor andobjectdepending on the response. 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