{"id":13773482,"url":"https://github.com/giulioz/react-ol-fiber","last_synced_at":"2025-04-15T01:15:25.620Z","repository":{"id":44804234,"uuid":"430747698","full_name":"giulioz/react-ol-fiber","owner":"giulioz","description":"🗺️⚛️  A React renderer for OpenLayers","archived":false,"fork":false,"pushed_at":"2022-03-08T12:08:25.000Z","size":2624,"stargazers_count":24,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-15T01:15:03.713Z","etag":null,"topics":["gis","maps","openlayers","react","wrapper"],"latest_commit_sha":null,"homepage":"https://react-ol-fiber.giuliozausa.dev/","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/giulioz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-22T14:49:38.000Z","updated_at":"2023-11-21T16:18:21.000Z","dependencies_parsed_at":"2022-08-25T13:02:00.784Z","dependency_job_id":null,"html_url":"https://github.com/giulioz/react-ol-fiber","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giulioz%2Freact-ol-fiber","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giulioz%2Freact-ol-fiber/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giulioz%2Freact-ol-fiber/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giulioz%2Freact-ol-fiber/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giulioz","download_url":"https://codeload.github.com/giulioz/react-ol-fiber/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248986315,"owners_count":21194025,"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":["gis","maps","openlayers","react","wrapper"],"created_at":"2024-08-03T17:01:16.106Z","updated_at":"2025-04-15T01:15:25.596Z","avatar_url":"https://github.com/giulioz.png","language":"TypeScript","funding_links":[],"categories":["Web (+ NW \u0026 Electron)"],"sub_categories":[],"readme":"# react-ol-fiber\n\n[![Version](https://img.shields.io/npm/v/react-ol-fiber)](https://npmjs.com/package/react-ol-fiber)\n[![Downloads](https://img.shields.io/npm/dt/react-ol-fiber.svg)](https://npmjs.com/package/react-ol-fiber)\n[![Test](https://github.com/giulioz/react-ol-fiber/actions/workflows/test.yml/badge.svg)](https://github.com/giulioz/react-ol-fiber/actions/workflows/test.yml)\n\nreact-ol-fiber is a \u003ca href=\"https://reactjs.org/docs/codebase-overview.html#renderers\"\u003eReact renderer\u003c/a\u003e for \u003ca href=\"https://openlayers.org/\"\u003eOpenLayers\u003c/a\u003e.\n\nBuild your maps declaratively with re-usable, self-contained components that react to state, are readily interactive and can participate in React's ecosystem.\n\n```bash\nnpm install ol react-ol-fiber\n```\n\nBeing a renderer and not a wrapper it's not tied to a specific version of OpenLayers, and allows easy extensibility.\n\n## Quick Start Code\n\n[![Edit react-ol-fiber-qs](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/react-ol-fiber-qs-32s5j?fontsize=14\u0026hidenavigation=1\u0026theme=dark\u0026view=preview)\n\n\u003cimg src=\"https://i.imgur.com/k5AerZY.gif\" /\u003e\n\n```tsx\nimport React, { useEffect, useState } from 'react';\nimport ReactDOM from 'react-dom';\nimport { MapComponent } from 'react-ol-fiber';\nimport 'ol/ol.css';\n\nfunction Shapes() {\n  const [active, setActive] = useState(false);\n  useEffect(() =\u003e {\n    const interval = setInterval(() =\u003e setActive(a =\u003e !a), 500);\n    return () =\u003e clearInterval(interval);\n  }, []);\n\n  return (\n    \u003cvectorLayer\u003e\n      \u003cstyleStyle\u003e\n        \u003cfillStyle arg={{ color: active ? 'blue' : 'yellow' }} /\u003e\n        \u003cstrokeStyle arg={{ color: 'red' }} /\u003e\n      \u003c/styleStyle\u003e\n\n      \u003cvectorSource\u003e\n        {new Array(32 * 32).fill(0).map((_, i) =\u003e (\n          \u003cfeature\u003e\n            \u003ccircleGeometry args={[[(i % 32) * 100000, Math.floor(i / 32) * 100000], 30000]} /\u003e\n          \u003c/feature\u003e\n        ))}\n      \u003c/vectorSource\u003e\n    \u003c/vectorLayer\u003e\n  );\n}\n\nfunction App() {\n  return (\n    \u003cMapComponent\u003e\n      \u003ctileLayer\u003e\n        \u003coSMSource /\u003e\n      \u003c/tileLayer\u003e\n\n      \u003cShapes /\u003e\n\n      \u003cdragPanInteraction /\u003e\n      \u003cmouseWheelZoomInteraction /\u003e\n    \u003c/MapComponent\u003e\n  );\n}\n\nReactDOM.render(\u003cApp /\u003e, document.getElementById('root'));\n```\n\n## Docs\n\n### The MapComponent component\n\nThe most important component in react-ol-fiber is `\u003cMapComponent /\u003e` it instantiate an OpenLayer `Map` object and mounts it in a full-width and full-height div. As children you can provide OpenLayer elements that can be mounted inside the map, such as layers, controls and interactions.\n\n```tsx\nfunction App() {\n  return (\n    \u003cMapComponent\n      view={{\n        center: fromLonLat([37.41, 8.82]),\n        zoom: 4,\n      }}\n    \u003e\n      \u003ctileLayer\u003e\n        \u003coSMSource /\u003e\n      \u003c/tileLayer\u003e\n    \u003c/MapComponent\u003e\n  );\n}\n```\n\n### Using OpenLayers classes\n\nTo create instances of OpenLayers classes in react-ol-fiber you can use JSX primitives. As component name, use the original class name with the first letter in lower case, followed by its category.\n\nTo provide arguments to the class constructor use the `args` prop, or `arg` if the constructor has a single parameter. To attach the children to the parent you can use the `attach` and `attachAdd` props (even though they are inferred automatically whenever possible by the reconciler).\n\nSome examples:\n\n```tsx\nfunction Component() {\n  return (\n    \u003c\u003e\n      \u003cfeature /\u003e {/* ol/Feature */}\n      \u003ctileLayer /\u003e {/* ol/layers/Tile */}\n      \u003cvectorLayer /\u003e {/* ol/layers/Vector */}\n      \u003ccircleGeometry args={[[0, 0], 10]} /\u003e {/* ol/geom/Circle */}\n      \u003cpointGeometry arg={[0, 0]} /\u003e {/* ol/geom/Point */}\n      \u003cdragPanInteraction /\u003e {/* ol/geom/Point */}\n      \u003cstyleStyle /\u003e {/* ol/style/Style */}\n      \u003cstrokeStyle arg={{ color: 'red', width: 2 }} /\u003e {/* ol/style/Stroke */}\n    \u003c/\u003e\n  );\n}\n```\n\n### Props\n\nThe props are applied using the setters found in the target object. The reconciler is optimized to call only the setters of the modified values.\n\n```tsx\nfunction Component() {\n  // This will call setOpacity in the VectorLayer\n  return \u003cvectorLayer opacity={0.75} /\u003e;\n}\n```\n\n### Event handlers\n\nAll the events described in the OpenLayers documentation are capitalized and prefixed with \"on\".\n\n```tsx\nfunction Component() {\n  // This will set the 'select' event\n  return \u003cselectInteraction onSelect={e =\u003e console.log(e)} /\u003e;\n\n  // This will set the 'change' event\n  return \u003cvectorSource onChange={e =\u003e console.log(e)} /\u003e;\n\n  // It also works on the map component!\n  return \u003cMapComponent onPointermove={e =\u003e console.log(e.coordinate)} /\u003e;\n}\n```\n\n### Hooks\n\nWhenever you need to access the underlying OpenLayers map instance, you can use the `useOL()` hook. Remember that this can work only inside a component that is child of a MapComponent. :warning:\n\n```tsx\nfunction Inner() {\n  const { map } = useOL();\n  function centerOnFeatures(extent: number[]) {\n    const view = map.getView();\n    view.fit(extent);\n  }\n\n  return (\n    \u003cvectorLayer\u003e\n      \u003cvectorSource onChange={e =\u003e centerOnFeatures(e.target.getExtent())}\u003e\n        \u003cfeature\u003e\n          \u003ccircleGeometry args={[[0, 0], 30000]} /\u003e\n        \u003c/feature\u003e\n      \u003c/vectorSource\u003e\n    \u003c/vectorLayer\u003e\n  );\n}\n\nfunction Parent() {\n  // WARNING: you can't use useOL() here\n  return (\n    \u003cMapComponent\u003e\n      \u003cInner /\u003e\n    \u003c/MapComponent\u003e\n  );\n}\n```\n\n### Spring Animation\n\nProvisional [react-spring](https://react-spring.io/) support is available! You can use the spring api to animate your maps, using the `a.` components. See [this example](https://github.com/giulioz/react-ol-fiber/blob/main/example/src/examples/Spring.tsx) to see how.\n\n### Using primitives\n\nIf you want to use your own already instanced objects, you can use the `olPrimitive` wrapper and set a custom attach:\n\n```tsx\nfunction Component() {\n  const features = myLoadFeatures();\n  return (\n    \u003cvectorSource\u003e\n      {features.map((feature, i) =\u003e (\n        \u003colPrimitive object={feature} key={i} attachAdd='feature' /\u003e\n      ))}\n    \u003c/vectorSource\u003e\n  );\n}\n```\n\n:warning: Using the `\u003colPrimitive /\u003e` instrinsic the props will not be checked. To have a generic primitive component, based on the `object` prop type, use the `\u003cOLPrimitive /\u003e` wrapper instead.\n\n### Using functions\n\nSometimes in OpenLayers it's convenient to use a function for some objects, such as style functions, to avoid creating too many objects.\n\n```tsx\nfunction Component() {\n  return (\n    \u003cvectorLayer\u003e\n      \u003colFn fn={feature =\u003e new Style({ fill: new Fill({ color: feature.get('color') }) })} attach='style' /\u003e\n\n      {/* OR */}\n\n      \u003colFn\n        fn={feature =\u003e (\n          \u003cstyleStyle\u003e\n            \u003cfillStyle arg={{ color: feature.get('color') }} /\u003e\n          \u003c/styleStyle\u003e\n        )}\n        attach='style'\n      /\u003e\n\n      \u003cvectorSource\u003e\n        \u003cfeature color='red'\u003e\n          \u003ccircleGeometry args={[[0, 0], 20000]} /\u003e\n        \u003c/feature\u003e\n      \u003c/vectorSource\u003e\n    \u003c/vectorLayer\u003e\n  );\n}\n```\n\n:warning: Please note that the second option, using JSX, does NOT use React to render the elements, it manually creates instances reading the JSX. Please use it with caution and DON'T use components in there.\n\n### Extending the catalogue\n\nTo extend the available components reachable by react-ol-fiber, you can use the `extend()` command. You can even implement your own props application logic using setters!\n\n```tsx\nimport BaseLayer from 'ol/layer/Base';\nclass MyLayer extends BaseLayer {\n  constructor(args: { ctorArg: boolean }) {\n    super({});\n  }\n\n  setMyNumber(value: number) {\n    console.log(value);\n  }\n}\n\nimport { extend, MapComponent, TypeOLCustomClass } from 'react-ol-fiber';\nextend({ MyLayer: MyLayer as any });\ndeclare global {\n  namespace JSX {\n    interface IntrinsicElements {\n      myLayer: TypeOLCustomClass\u003ctypeof MyLayer\u003e;\n    }\n  }\n}\n\nfunction Test() {\n  return (\n    \u003cMapComponent\u003e\n      \u003cmyLayer arg={{ ctorArg: false }} myNumber={42} /\u003e\n    \u003c/MapComponent\u003e\n  );\n}\n```\n\n## FAQ\n\n### I'm not seeing my map and the entire page is blank\n\nYou need to add make your parent DOM elements full-height:\n\n```css\nhtml,\nbody,\n#root {\n  width: 100%;\n  height: 100%;\n  margin: 0;\n}\n```\n\n## Credits\n\nThis library was strongly inspired by \u003ca href=\"https://github.com/pmndrs/react-three-fiber\"\u003ereact-three-fiber\u003c/a\u003e and the technical details given by this amazing \u003ca href=\"https://codyb.co/articles/a-technical-breakdown-of-react-three-fiber\"\u003earticle\u003c/a\u003e by Cody Bennet.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiulioz%2Freact-ol-fiber","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiulioz%2Freact-ol-fiber","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiulioz%2Freact-ol-fiber/lists"}