{"id":28956698,"url":"https://github.com/developmentseed/stac-react","last_synced_at":"2025-06-23T21:40:34.177Z","repository":{"id":40465253,"uuid":"487001872","full_name":"developmentseed/stac-react","owner":"developmentseed","description":"React components and hooks for building STAC-API front-ends","archived":false,"fork":false,"pushed_at":"2024-03-08T03:42:55.000Z","size":295,"stargazers_count":25,"open_issues_count":3,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-21T13:43:43.268Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/developmentseed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-04-29T14:26:58.000Z","updated_at":"2024-09-25T12:15:09.000Z","dependencies_parsed_at":"2024-03-08T04:31:26.308Z","dependency_job_id":"bfad6e1a-55a4-4ad8-b60d-bf71d0cf204f","html_url":"https://github.com/developmentseed/stac-react","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/developmentseed/stac-react","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fstac-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fstac-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fstac-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fstac-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/developmentseed","download_url":"https://codeload.github.com/developmentseed/stac-react/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/developmentseed%2Fstac-react/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261211684,"owners_count":23125543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-23T21:40:33.337Z","updated_at":"2025-06-23T21:40:34.145Z","avatar_url":"https://github.com/developmentseed.png","language":"TypeScript","readme":"# stac-react\n\nReact hooks to build front-end applications for STAC APIs. \n\n\u003e **Note:**\n\u003e stac-react is in early development, the API will likely break in future versions. \n\n## Installation\n\nWith NPM:\n\n```sh\nnpm i @developmentseed/stac-react\n```\n\nWith Yarn:\n\n```sh\nyarn add @developmentseed/stac-react\n```\n\n## Getting started\n\nStac-react's hooks must be used inside children of a React context that provides access to the stac-react's core functionality. \n\nTo get started, initialize `StacApiProvider` with the base URL of the STAC catalog. \n\n```jsx\nimport { StacApiProvider } from \"stac-react\";\n\nfunction StacApp() {\n  return (\n    \u003cStacApiProvider apiUrl=\"https://my-stac-api.com\"\u003e\n      // Other components\n    \u003c/StacApiProvide\u003e\n  );\n}\n```\n\nNow you can start using stac-react hooks in child components of `StacApiProvider`\n\n```jsx\nimport { StacApiProvider, useCollections } from \"stac-react\";\n\nfunction Collections() {\n  const { collections } = useCollections();\n  \n  return (\n\t  \u003cul\u003e\n\t    {collections.collections.map(({ id, title }) =\u003e (\n\t      \u003cli key={id}\u003e{ title }\u003c/li\u003e\n\t    ))}\n\t  \u003c/ul\u003e\n    \n  )\n}\n\nfunction StacApp() {\n  return (\n    \u003cStacApiProvider apiUrl=\"https://my-stac-api.com\"\u003e\n      \u003cCollections /\u003e\n    \u003c/StacApiProvide\u003e\n  );\n}\n```\n\n## API\n\n### StacApiProvider\n\nProvides the React context required for stac-react hooks. \n\n#### Initialization\n\n```jsx\nimport { StacApiProvider } from \"stac-react\";\n\nfunction StacApp() {\n  return (\n    \u003cStacApiProvider apiUrl=\"https://my-stac-api.com\"\u003e\n      // Other components\n    \u003c/StacApiProvide\u003e\n  );\n}\n```\n\n##### Component Properties\n\nOption          | Type      | Description\n--------------- | --------- | -------------\n`apiUrl`.       | `string`  | The base url of the STAC catalog.\n\n### useCollections\n\nRetrieves collections from a STAC catalog.\n\n#### Initialization\n\n```js\nimport { useCollections } from \"stac-react\";\nconst { collections } = useCollections();\n```\n\n#### Return values\n\nOption          | Type      | Description\n--------------- | --------- | -------------\n`collections`   | `array`   | A list of collections available from the STAC catalog. Is `null` if collections have not been retrieved.\n`state`         | `str`     | The status of the request. `\"IDLE\"` before and after the request is sent or received. `\"LOADING\"` when the request is in progress. \n`reload`        | `function`| Callback function to trigger a reload of collections.\n`error`         | [`Error`](#error)   | Error information if the last request was unsuccessful. `undefined` if the last request was successful. \n\n#### Example\n\n```js\nimport { useCollections } from \"stac-react\";\n\nfunction CollectionList() {\n  const { collections, state } = useCollections();\n\n  if (state === \"LOADING\") {\n    return \u003cp\u003eLoading collections...\u003c/p\u003e\n  }\n\n  return (\n    \u003c\u003e\n    {collections ? (\n      \u003cul\u003e\n        {collections.collections.map(({ id, title }) =\u003e (\n          \u003cli key={id}\u003e{title}\u003c/li\u003e\n        ))}\n      \u003c/ul\u003e\n      \u003cbutton type=\"button\" onclick={reload}\u003eUpdate collections\u003c/button\u003e\n    ): (\n      \u003cp\u003eNo collections\u003c/p\u003e\n    )}\n    \u003c/\u003e\n  );\n}\n```\n\n### useCollection\n\nRetrieves a single collection from the STAC catalog. \n\n#### Initialization\n\n```js\nimport { useCollection } from \"stac-react\";\nconst { collection } = useCollection(id);\n```\n\n#### Parameters\n\nOption          | Type      | Description\n--------------- | --------- | -------------\n`id`            | `string`  | The collection ID. \n\n#### Return values\n\nOption          | Type      | Description\n--------------- | --------- | -------------\n`collection`    | `object`  | The collection matching the provided ID. Is `null` if collection has not been retrieved.\n`state`         | `str`     | The status of the request. `\"IDLE\"` before and after the request is sent or received. `\"LOADING\"` when the request is in progress. \n`reload`        | `function`| Callback function to trigger a reload of the collection.\n`error`         | [`Error`](#error)   | Error information if the last request was unsuccessful. `undefined` if the last request was successful. \n\n#### Example\n\n```js\nimport { useCollection } from \"stac-react\";\n\nfunction Collection() {\n  const { collection, state } = useCollection(\"collection_id\");\n\n  if (state === \"LOADING\") {\n    return \u003cp\u003eLoading collection...\u003c/p\u003e\n  }\n\n  return (\n    \u003c\u003e\n    {collection ? (\n      \u003c\u003e\n        \u003ch2\u003e{collection.id}\u003c/h2\u003e\n        \u003cp\u003e{collection.description}\u003c/p\u003e\n      \u003c/\u003e\n    ) : (\n      \u003cp\u003eNot found\u003c/p\u003e\n    )}\n    \u003c/\u003e\n  );\n}\n```\n\n### useItem\n\nRetrieves an item from the STAC catalog. To retrieve an item, provide its full url to the `useItem` hook.\n\n#### Initialization\n\n```js\nimport { useItem } from \"stac-react\";\nconst { item } = useItem(url);\n```\n\n#### Parameters\n\nOption          | Type      | Description\n--------------- | --------- | -------------\n`url`           | `string`  | The URL of the item you want to retrieve.  \n\n#### Return values\n\nOption          | Type      | Description\n--------------- | --------- | -------------\n`item`          | `object`  | The item matching the provided URL.\n`state`         | `str`     | The status of the request. `\"IDLE\"` before and after the request is sent or received. `\"LOADING\"` when the request is in progress. \n`reload`        | `function`| Callback function to trigger a reload of the item.\n`error`         | [`Error`](#error)   | Error information if the last request was unsuccessful. `undefined` if the last request was successful. \n\n#### Examples\n\n```js\nimport { useItem } from \"stac-react\";\n\nfunction Item() {\n  const { item, state } = useItem(\"https://stac-catalog.com/items/abc123\");\n\n  if (state === \"LOADING\") {\n    return \u003cp\u003eLoading item...\u003c/p\u003e\n  }\n\n  return (\n    \u003c\u003e\n    {item ? (\n      \u003c\u003e\n        \u003ch2\u003e{item.id}\u003c/h2\u003e\n        \u003cp\u003e{items.description}\u003c/p\u003e\n      \u003c/\u003e\n    ) : (\n      \u003cp\u003eNot found\u003c/p\u003e\n    )}\n    \u003c/\u003e\n  );\n}\n```\n\n### useStacSearch\n\nExecutes a search against a STAC API using the provided search parameters.\n\n#### Initialization\n\n```js\nimport { useStacSearch } from \"stac-react\";\nconst { results } = useStacSearch();\n```\n\n#### Return values\n\nOption             | Type      | Description\n------------------ | --------- | -------------\n`submit`           | `function` | Callback to submit the search using the current filter parameters. Excecutes an API call to the specified STAC API.\n`ids`              | `array\u003cstring\u003e`   | List of item IDs to match in the search, `undefined` if unset.\n`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.\n`bbox`             | `array\u003cnumber\u003e`   | Array of coordinates `[northWestLon, northWestLat, southEastLon, southEastLat]`, `undefined` if unset.\n`setBbox(bbox)`    | `function` | Callback to set `bbox`. `bbox` must be an array of coordinates `[northWestLon, northWestLat, southEastLon, southEastLat]`, or `undefined` to reset.\n`collections`      | `array\u003cstring\u003e`   | List of select collection IDs included in the search query. `undefined` if unset.\n`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. \n`dateRangeFrom`    | `string` | The from-date of the search query. `undefined` if unset.\n`setDateRangeFrom(fromDate)` | `function` | Callback to set `dateRangeFrom`. `fromDate` must be ISO representation of a date, ie. `2022-05-18`, or `undefined` to reset.\n`dateRangeTo`      | `string` | The to-date of the search query. `undefined` if unset.\n`setDateRangeTo(toDate)`   | `function` | Callback to set `dateRangeto`. `toDate` must be ISO representation of a date, ie. `2022-05-18`, or `undefined` to reset.\n`sortby`             | `array`   | Specifies the order of results. Array of `{ field: string, direction: 'asc' | 'desc' }`\n`setSortby(sort)`          | `function` | Callback to set `sortby`. `sort` must be an array of `{ field: string, direction: 'asc' | 'desc' }`, or `undefined` to reset.\n`limit`            | `number`   | The number of results returned per result page.\n`setLimit(limit)`  | `function` | Callback to set `limit`. `limit` must be a `number`, or `undefined` to reset.\n`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. \n`state`            | `string` | The status of the request. `\"IDLE\"` before and after the request is sent or received. `\"LOADING\"` when the request is in progress. \n`error`            | [`Error`](#error)   | Error information if the last request was unsuccessful. `undefined` if the last request was successful. \n`nextPage`         | `function` | Callback function to load the next page of results. Is `undefined` if the last page is the currently loaded.\n`previousPage`     | `function` | Callback function to load the previous page of results. Is `undefined` if the first page is the currently loaded.\n\n#### Examples\n\n##### Render results\n\n```jsx\nimport { useStacSearch } from \"stac-react\";\n\nfunction StacComponent() {\n  const { result } = useStacSearch();\n\n  return (\n    \u003c\u003e\n      \u003cdiv class=\"item-list\"\u003e\n        {results \u0026\u0026 (\n          \u003cul\u003e\n            {results.features.map(({ id }) =\u003e (\n              \u003cli key={id}\u003e{ id }\u003c/li\u003e\n            ))}\n          \u003c/ul\u003e\n        )}\n      \u003c/div\u003e\n    \u003c/\u003e\n  )\n}\n```\n\n##### Handle errors\n\n```jsx\nimport { useCallback } from \"react\";\nimport { useStacSearch } from \"stac-react\";\n\nimport Map from \"./map\";\n\nfunction StacComponent() {\n  const { error, result } = useStacSearch();\n\n  return (\n    \u003c\u003e\n      \u003cdiv class=\"item-list\"\u003e\n        {error \u0026\u0026 \u003cp\u003e{ error.detail }\u003c/p\u003e}\n        {results \u0026\u0026 (\n          \u003cul\u003e\n            {results.features.map(({ id }) =\u003e (\n              \u003cli key={id}\u003e{ id }\u003c/li\u003e\n            ))}\n          \u003c/ul\u003e\n        )}\n      \u003c/div\u003e\n    \u003c/\u003e\n  )\n}\n```\n\n##### Pagination\n\n```jsx\nimport { useStacSearch } from \"stac-react\";\n\nfunction StacComponent() {\n  const {\n    nextPage,\n    previousPage,\n    result\n  } = useStacSearch();\n\n  return (\n    \u003c\u003e\n      \u003cdiv class=\"item-list\"\u003e\n        {results \u0026\u0026 (\n          // render results\n        )}\n      \u003c/div\u003e\n      \u003cdiv class=\"pagination\"\u003e\n        \u003cbutton type=\"button\" disabled={!previousPage} onClick={previousPage}\u003e\n        \u003cbutton type=\"button\" disabled={!nextPage} onClick={nextPage}\u003e\n      \u003c/div\u003e\n    \u003c/\u003e\n  )\n}\n```\n\n##### Set collections\n\n```jsx\nimport { useStacSearch } from \"stac-react\";\n\nfunction StacComponent() {\n  const { collections } = useCollections();\n  const { collections: selectedCollections, setCollections, results, submit } = useStacSearch();\n\n  const handleChange = useCallback((event) =\u003e {\n    const { value } = event.target;\n\n    const nextValues = selectedCollections.includes(value)\n      ? selectedCollections.filter((v) =\u003e v !== value)\n      : [ ...selectedCollections, value ];\n\n    setCollections(nextValues);\n  }, [selectedCollections, setCollections]);\n\n  return (\n    \u003c\u003e\n      \u003cdiv class=\"query-builder\"\u003e\n        \u003cform onSubmit={submit}\u003e\n          \u003cfieldset\u003e\n            \u003clegend\u003eSelect collections\u003c/legend\u003e\n            {collections.map(({ id, title }) =\u003e (\n              \u003cinput \n                id={id}\n                name=\"collections\"\n                value={id}\n                type=\"checkbox\"\n                onChange={handleChange}\n                checked={selectedCollections.includes(id)}\n              /\u003e\n              \u003clabel htmlFor={id}\u003e{title}\u003c/label\u003e\n            ))}\n          \u003cfieldset\u003e\n          \u003cbutton type=\"submit\"\u003eSearch\u003c/button\u003e\n        \u003c/form\u003e\n      \u003c/div\u003e\n    \u003c/\u003e\n  )\n}\n```\n\n##### Set bounding box\n\n```jsx\nimport { useCallback } from \"react\";\nimport { useStacSearch } from \"stac-react\";\n\nfunction StacComponent() {\n  const { bbox, setBbox, submit } = useStacSearch();\n\n  const handleDrawComplete = useCallback((feature) =\u003e {\n    setIsBboxDrawEnabled(false);\n    \n    const { coordinates } = feature.geometry;\n    const bbox = [...coordinates[0][0], ...coordinates[0][2]];\n    setBbox(bbox);\n  }, [setBbox]);\n\n  \u003cMap handleDrawComplete={handleDrawComplete} /\u003e\n}\n```\n\nThis 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.\n\n##### Set date range\n\n```jsx\nimport { useStacSearch } from \"stac-react\";\n\nfunction StacComponent() {\n  const {\n    dateRangeFrom,\n    setDateRangeFrom,\n    dateRangeTo,\n    setDateRangeTo,\n    submit\n  } = useStacSearch();\n\n  return (\n    \u003c\u003e\n      \u003cinput type=\"date\" name=\"date_from\" onChange={setDateRangeFrom} value={dateRangeFrom} /\u003e\n      \u003cinput type=\"date\" name=\"date_to\" onChange={setDateRangeTo} value={dateRangeTo} /\u003e\n      \u003cbutton type=\"button\" onclick={submit}\u003e\n    \u003c/\u003e\n  )\n}\n```\n\n### Types\n\n#### Error\n\n```js\n{\n  detail: \"Invalid bbox object\"\n  status: 400,\n  statusText: \"Bad Request\"\n}\n```\n\nOption             | Type      | Description\n------------------ | --------- | -------------\n`detail`           | `string` | `object | The error return from the API. Either a `string` or and `object` depending on the response. \n`status`           | `number` | HTTP status code of the response.\n`statusText`       | `string` | Status text for the response. \n\n\n## Development\n\nRun tests\n\n```sh\nyarn test\n```\n\nLint\n\n```sh\nyarn lint\n```\n\nBuild\n\n```\nyarn build\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevelopmentseed%2Fstac-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevelopmentseed%2Fstac-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevelopmentseed%2Fstac-react/lists"}