https://github.com/developmentseed/stac-react
React components and hooks for building STAC-API front-ends
https://github.com/developmentseed/stac-react
Last synced: 10 months ago
JSON representation
React components and hooks for building STAC-API front-ends
- Host: GitHub
- URL: https://github.com/developmentseed/stac-react
- Owner: developmentseed
- License: mit
- Created: 2022-04-29T14:26:58.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-03-08T03:42:55.000Z (about 2 years ago)
- Last Synced: 2025-05-21T13:43:43.268Z (11 months ago)
- Language: TypeScript
- Size: 288 KB
- Stars: 25
- Watchers: 2
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```sh
npm i @developmentseed/stac-react
```
With Yarn:
```sh
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.
```jsx
import { StacApiProvider } from "stac-react";
function StacApp() {
return (
// Other components
);
}
```
Now you can start using stac-react hooks in child components of `StacApiProvider`
```jsx
import { StacApiProvider, useCollections } from "stac-react";
function Collections() {
const { collections } = useCollections();
return (
- { title }
{collections.collections.map(({ id, title }) => (
))}
)
}
function StacApp() {
return (
);
}
```
## API
### StacApiProvider
Provides the React context required for stac-react hooks.
#### Initialization
```jsx
import { StacApiProvider } from "stac-react";
function StacApp() {
return (
// Other components
);
}
```
##### Component Properties
Option | Type | Description
--------------- | --------- | -------------
`apiUrl`. | `string` | The base url of the STAC catalog.
### useCollections
Retrieves collections from a STAC catalog.
#### Initialization
```js
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) | Error information if the last request was unsuccessful. `undefined` if the last request was successful.
#### Example
```js
import { useCollections } from "stac-react";
function CollectionList() {
const { collections, state } = useCollections();
if (state === "LOADING") {
return
Loading collections...
}
return (
<>
{collections ? (
- {title}
{collections.collections.map(({ id, title }) => (
))}
Update collections
): (
No collections
)}
>
);
}
```
### useCollection
Retrieves a single collection from the STAC catalog.
#### Initialization
```js
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) | Error information if the last request was unsuccessful. `undefined` if the last request was successful.
#### Example
```js
import { useCollection } from "stac-react";
function Collection() {
const { collection, state } = useCollection("collection_id");
if (state === "LOADING") {
return
Loading collection...
}
return (
<>
{collection ? (
<>
{collection.id}
{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
```js
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) | Error information if the last request was unsuccessful. `undefined` if the last request was successful.
#### Examples
```js
import { useItem } from "stac-react";
function Item() {
const { item, state } = useItem("https://stac-catalog.com/items/abc123");
if (state === "LOADING") {
return
Loading item...
}
return (
<>
{item ? (
<>
{item.id}
{items.description}
>
) : (
Not found
)}
>
);
}
```
### useStacSearch
Executes a search against a STAC API using the provided search parameters.
#### Initialization
```js
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` | 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` | 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` | 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](https://github.com/radiantearth/stac-api-spec/blob/v1.0.0-rc.2/fragments/itemcollection/README.md). `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) | 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
```jsx
import { useStacSearch } from "stac-react";
function StacComponent() {
const { result } = useStacSearch();
return (
<>
{results && (
- { id }
{results.features.map(({ id }) => (
))}
)}
>
)
}
```
##### Handle errors
```jsx
import { useCallback } from "react";
import { useStacSearch } from "stac-react";
import Map from "./map";
function StacComponent() {
const { error, result } = useStacSearch();
return (
<>
{error &&
{ error.detail }
}{results && (
- { id }
{results.features.map(({ id }) => (
))}
)}
>
)
}
```
##### Pagination
```jsx
import { useStacSearch } from "stac-react";
function StacComponent() {
const {
nextPage,
previousPage,
result
} = useStacSearch();
return (
<>
{results && (
// render results
)}
>
)
}
```
##### Set collections
```jsx
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 (
<>
Select collections
{collections.map(({ id, title }) => (
{title}
))}
Search
>
)
}
```
##### Set bounding box
```jsx
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]);
}
```
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
```jsx
import { useStacSearch } from "stac-react";
function StacComponent() {
const {
dateRangeFrom,
setDateRangeFrom,
dateRangeTo,
setDateRangeTo,
submit
} = useStacSearch();
return (
<>
>
)
}
```
### Types
#### Error
```js
{
detail: "Invalid bbox object"
status: 400,
statusText: "Bad Request"
}
```
Option | Type | Description
------------------ | --------- | -------------
`detail` | `string` | `object | The error return from the API. Either a `string` or and `object` depending on the response.
`status` | `number` | HTTP status code of the response.
`statusText` | `string` | Status text for the response.
## Development
Run tests
```sh
yarn test
```
Lint
```sh
yarn lint
```
Build
```
yarn build
```