{"id":25774436,"url":"https://github.com/markusand/mapbox-composition","last_synced_at":"2025-02-27T05:29:58.387Z","repository":{"id":50332523,"uuid":"362544650","full_name":"markusand/mapbox-composition","owner":"markusand","description":"Wrapper to use mapbox-gl with Composition API","archived":false,"fork":false,"pushed_at":"2024-12-28T16:00:38.000Z","size":978,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-12-28T16:31:32.894Z","etag":null,"topics":["composition","map","mapbox"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markusand.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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,"publiccode":null,"codemeta":null}},"created_at":"2021-04-28T16:54:34.000Z","updated_at":"2024-12-28T16:00:41.000Z","dependencies_parsed_at":"2025-01-04T12:00:22.327Z","dependency_job_id":null,"html_url":"https://github.com/markusand/mapbox-composition","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusand%2Fmapbox-composition","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusand%2Fmapbox-composition/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusand%2Fmapbox-composition/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusand%2Fmapbox-composition/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markusand","download_url":"https://codeload.github.com/markusand/mapbox-composition/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240983671,"owners_count":19888738,"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":["composition","map","mapbox"],"created_at":"2025-02-27T05:29:57.910Z","updated_at":"2025-02-27T05:29:58.377Z","avatar_url":"https://github.com/markusand.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mapbox Composition\n\nWrapper to use Mapbox GL with Composition API\n\n[![NPM](https://img.shields.io/npm/v/mapbox-composition)](https://npmjs.org/package/mapbox-composition)\n[![NPM](https://img.shields.io/bundlephobia/minzip/mapbox-composition)](https://npmjs.org/package/mapbox-composition)\n[![NPM](https://img.shields.io/npm/l/mapbox-composition)](https://npmjs.org/package/mapbox-composition)\n\n## Install\n\n```bash\nnpm i mapbox-gl mapbox-composition @types/mapbox-gl\n```\n\n## Usage\n\n```javascript\nimport { onMounted } from 'vue';\nimport { createMap, useControls, useGeoJSON, useMarker, usePopup } from 'mapbox-composition';\n\nconst { MAPBOX_TOKEN } = process.env;\n\nexport default {\n  name: 'Map',\n  setup() {\n    onMounted(async () =\u003e {\n      const map = await createMap('map', {\n        accessToken: MAPBOX_TOKEN,\n        style: 'mapbox://styles/mapbox/light-v9',\n        center: [-122.447303, 37.753574],\n        zoom: 12,\n      });\n\n      const { addNavigation } = useControls(map);\n      addNavigation({ position: 'top-left' });\n\n      useGeoJSON(map, {\n        id: 'facilities',\n        source: 'https://data.sfgov.org/resource/nc68-ngbr.geojson',\n        layers: [\n          { name: 'markers', type: 'circle', paint: { 'circle-color': '#39f' } },\n          { name: 'labels', type: 'symbol', layout: { 'text-field': 'common-name' } },\n        ],\n      });\n\n      useMarker(map, {\n        coordinates: [-122.426498, 37.772496],\n        popup: usePopup({ content: 'Painted Ladies' }),\n      });\n    });\n\n    return {};\n  },\n};\n```\n\n### createMap(container, options)\n\nLoad a map. This function must be called inside the onMounted hook, after the DOM container has been mounted.\n\nLoad is asynchronous, and the function returns a promise that resolves to the Mapbox map instance. Use async/await pattern.\n\n```javascript\nonMounted(async () =\u003e {\n  const map = await createMap('map', { /* Options */ });\n});\n```\n\nOptions object accepts all Mapbox [Map parameters](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters). Can also include a `controls` attrtbiute with options to automatically initialize controls at map load. Add a debounce parameter to control the resize timing.\n\nHandlers for any [map event](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-events) can be added using the event name prefixed with `on`, such as follows\n\n```javascript\ncreateMap('map', {\n  // Many options...\n  onZoomend: () =\u003e console.log('Zoom End'),\n  onDragend: () =\u003e console.log('Dragged'),\n})\n```\n\n### useTerrain(map, options)\n\n\u003e Mapbox-gl v2+ is required to use 3D terrain\n\nUse an extruded 3D map and parametrize the [Sky API options](https://www.mapbox.com/blog/sky-api-atmospheric-scattering-algorithm-for-3d-maps) and [fog options](https://www.mapbox.com/blog/mapbox-gl-js-v2-3-0-distance-fog-elevation-querying-and-terrain-performance-improvements).\nReturns `extrude({ exaggeration, pitch })`, `flatten()`, and `isExtruded()` methods.\n\n```javascript\nconst sky = { /* sky options */ };\nconst { extrude } = useTerrain(map, { sky });\nextrude({ exaggeration: 1.5, pitch: 40 });\n```\n\n### useControls(map)\n\nAdd map controls.\n\n```javascript\nimport LegendControl from 'mapboxgl-legend';\nconst legend = new LegendControl({ /* options */});\n\nconst { addControl, removeControl } = useControls(map);\naddControl('legend', 'top-left', legend);\nremoveControl('legend');\n```\n\nShorthands to default [Mapbox controls](https://docs.mapbox.com/mapbox-gl-js/api/markers/#icontrol)\n`addNavigation`, `addScale`, `addGeolocate`, `addAttribution`, `addFullscreen` and all remove counterparts. Options object may include `position` and any attribute described in particular control documentation.\n\n```javascript\nconst { addNavigation, addScale } = useControls(map);\naddNavigation();\naddScale({ position: 'bottom-right', maxWidth: 150 });\n```\n\nA custom `addStyles` control is available to switch between map styles. Switch buttons accept a text label or an image. Styles can be customized via [variables](./src/controls/styles.control.css).\n\n```javascript\nconst { addStyles } = useControls(map);\naddStyles({\n  styles: [\n    {\n      name: 'Mapbox Light',\n      url: 'mapbox://styles/mapbox/light-v10',\n      label: 'Light',\n      // img: '/images/map/thumb.contours.jpg',\n    },\n    {\n      name: 'Mapbox Satellite',\n      url: 'mapbox://styles/mapbox/satellite-v9',\n      label: 'Satellite',\n      // img: '/images/map/thumb.satellite.jpg',\n    },\n  ]\n})\n```\n\nA custom `addTerrain` control is available to seamlessly toggle 3D map extrusion.\n\n```javascript\nconst { addTerrain } = useControls(map);\naddTerrain({\n  sky: { /* sky options */ },\n  exaggeration: 1.5,\n  pitch: 40,\n  extrudeOnInit: true,\n});\n```\n\n### useAsync(map)\n\nUse promisified versions of mapbox actions such as `easeTo`, `flyTo`, `fitBounds`, `zoomIn`, etc. and detect its end.\n\n```javascript\nconst { flyTo } = useAsync(map);\nconsole.log('Going to Berkeley');\nawait flyTo({ center: [-122.272998, 37.871559] });\nconsole.log('Arrived at Berkeley');\n```\n\n### useDataset(map, options)\n\nLoad many layers to map. Options accept `source` and `layers` attributes, being source any valid style specification [Source](https://docs.mapbox.com/mapbox-gl-js/style-spec/sources) and being every layers object a valid style specification [Layer](https://docs.mapbox.com/mapbox-gl-js/style-spec/layers). Note layer options do not need a `source` attribute as will directly take the source name.\n\nThe `source` parameter accepts a promise to load async data. Additionaly, use the `setSource` method to initialize the data at convenience, for example after a user interaction.\n\nSources and layers are restored by default after map style changes. To disable this behaviour, set `persist` attribute to false on layer config object.\n\nLayers can be placed under another specific layer by setting the attribute `under` with the name of that layer. This attribute can be global or per layer basis.\n\nOptions object may include event handlers for source events `onError`, `onLoadStart`, `onLoadEnd` and layer events `onClick` and `onHover`.\n\n```javascript\nconst dataset = useDataset(map, {\n  name: 'gkhj45665',\n  source: {\n    type: 'vector',\n    url: 'http://api.example.com/tilejson.json',\n  },\n  layers: [\n    { /* Layer options */ },\n    { /* Other layer options */ },\n  ],\n  onClick: ({ features }) =\u003e console.log(features),\n});\n```\n\nThe function returns manipulators for layers `isVisible(layer_id)`, `setVisibility(isVisible, [,layer_names])`, `setFilters(filters, [,layer_names])`, `clearLayers([layer_names])`, `updateLayers(layers)`, `addLayers(layers)`, `clearSource`, `setSource(source)`. If the layer_names array is not provided, the action will be performed to all layers.\n\n```javascript\nconst { setVisibility, setFilters, updateSource } = useGeoJSON(map, { /* options */ });\nsetFilters(['==', ['get', 'type'], 'hospital']);\nsetVisibility(false, ['layer--1']);\nupdateSource('http://api.example.com/data/example.geojson');\n```\n\nuseDataset does not return an `updateSource(source, [,layers])` method. Use provided helper shortcuts to improve typing and performance, and to modify data afterwards.\n\n```javascript\nconst geojsonLayer = useGeoJSON(map, /* GeoJSON options */)\nconst imageLayer = useImage(map, /* Images options */)\nconst videoLayer = useVideo(map, /* Video options */)\nconst tilesLayer = useTiles(map, /* Vector or aster tiles options */)\n```\n\nThis shortcuts also include an `authToken` parameter to set source based authentication with bearer token. Use `updateToken` from the auth returned atribute to refresh expirable tokens such as JWT.\n\n### useMarker(map, options)\n\nDisplay a marker on the map. Options object accepts any valid [Marker parameters](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker-parameters) and may include `onDragStart`, `onDrag` and `onDragEnd` event handlers.\n\nThe default Mapbox marker is applied unless a specific `element` is defined.\n\n```javascript\nconst pulseMarker = document.createElement('div');\npulseMarker.classList.add('pulse-marker');\n\nconst marker = useMarker(map, {\n  element: pulseMarker,\n  coordinates: [-122.447303, 37.753574],\n  onDragEnd: () =\u003e console.log('Marker dragged');\n});\n```\n\nThe function returns a `setLocation` modificator, a getter for the Mapbox marker instance and getter/setter for a popup.\n\n### usePopup([map,] options)\n\nDisplay a popup on the map. Options object accepts any valid [Popup parameter](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup-parameters) and may include `onOpen` and `onClose` event handlers.\n\nUse `coordinates` to assign the location of the popup. Popup accepts HTML content with the `content` attribute.\n\n```javascript\nconst popup = usePopup(map, {\n  name: 'my-popup',\n  coordinates: [-122.447303, 37.753574],\n  content: '\u003ch1\u003eI am a popup\u003c/h1\u003e',\n  closeOnClick: false,\n  onClose: () =\u003e console.log('Popup closed'),\n});\n```\n\nThe function returns `setLocation` and `setContent` modificators, and getters for `name` and the Mapbox popup instance.\n\nIf no `content` is provided, a container div is created with the `name` id (must be unique), and more complex layouts can be created using patterns like Vue's [teleport](https://v3.vuejs.org/guide/teleport.html).\n\n```html\n\u003cTeleport v-if=\"showPopup\" to=\"#my-popup\"\u003e\n  \u003c!-- Complex HTML layout --\u003e\n\u003c/Teleport\u003e\n```\n\nThe `map` attribute is not required when binding popup to a marker, as well as the `coordinates` options parameter.\n\n```javascript\n// Add popup on marker creation as a parameter\nconst marker = useMarker(map, {\n  ...OPTIONS,\n  popup: usePopup({ content: 'A popup for this marker' }),\n})\n\n// Or add popup dynamically\nconst marker = useMarker(map, OPTIONS);\nmarker.popup = usePopup({ content: 'A popup for this marker' });\n```\n\n### useImages(map)\n\nLoad images to be used as icons on the map.\n\nReturns `addImages(images, options)` and `removeImages(images)`. Images are added asynchronously and are not displayed on the map until they are loaded.\n\nOptions object accepts `persist` attribute (defaults to true) to reload images after map style changes. Also accepts `sdf`, stretching, and `pixelRatio` [image parameters](https://docs.mapbox.com/mapbox-gl-js/api/map/#addimage-parameters).\n\n```javascript\nconst images = {\n  'my-icon': 'https://example.com/my-icon.png',\n  'my-other': 'https://example.com/my-other.png',\n};\nconst { addImages, removeImages } = useImages(map);\nawait addImages(images, { sdf: true });\n\nremoveImages(images);\n// or removeImages(['my-icon', 'my-other']);\n```\n\n### Helpers\n\nPackage exports helper utilities.\n\nAt the moment there is only a `bbox` method that receives a a Feature or FeatureCollection and returns its containing bounding box.\n\n## Contribute\n\nContributions are welcome. Feel free to open a pull request.\n\nBy contributing to this project, you agree to license your contributions under the terms of the ISC License.\n\n## License\n\nThis package is licensed under the [ISC License](./LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusand%2Fmapbox-composition","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkusand%2Fmapbox-composition","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusand%2Fmapbox-composition/lists"}