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

developmentseed / stac-react

stac-react

Installation

Getting started

API

StacApiProvider

Initialization

Component Properties

useCollections

Initialization

Return values

Example

useCollection

Initialization

Parameters

Return values

Example

useItem

Initialization

Parameters

Return values

Examples

useStacSearch

Initialization

Return values

Examples

Render results

Handle errors

Pagination

Set collections

Set bounding box

Set date range

Types

Error

Development

About

Languages