{"id":13569120,"url":"https://github.com/markusand/mapboxgl-legend","last_synced_at":"2025-04-05T11:12:33.555Z","repository":{"id":57291157,"uuid":"323394751","full_name":"markusand/mapboxgl-legend","owner":"markusand","description":"Add a legend to a mapbox-gl map by parsing layer layout \u0026 paint expressions.","archived":false,"fork":false,"pushed_at":"2024-12-27T01:07:58.000Z","size":1723,"stargazers_count":51,"open_issues_count":1,"forks_count":14,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T10:09:36.718Z","etag":null,"topics":["legend","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":"isc","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","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":"2020-12-21T16:46:30.000Z","updated_at":"2024-12-27T08:48:24.000Z","dependencies_parsed_at":"2024-01-14T03:49:29.974Z","dependency_job_id":"1afea20b-10b8-49ea-b7d4-0edcbc74c9e5","html_url":"https://github.com/markusand/mapboxgl-legend","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusand%2Fmapboxgl-legend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusand%2Fmapboxgl-legend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusand%2Fmapboxgl-legend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusand%2Fmapboxgl-legend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markusand","download_url":"https://codeload.github.com/markusand/mapboxgl-legend/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325695,"owners_count":20920714,"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":["legend","map","mapbox"],"created_at":"2024-08-01T14:00:36.169Z","updated_at":"2025-04-05T11:12:33.523Z","avatar_url":"https://github.com/markusand.png","language":"TypeScript","funding_links":[],"categories":["Third-Party Resources"],"sub_categories":["Libraries"],"readme":"# mapboxgl-legend\n\n[![NPM](https://img.shields.io/npm/v/mapboxgl-legend)](https://npmjs.org/package/mapboxgl-legend)\n[![NPM](https://img.shields.io/bundlephobia/minzip/mapboxgl-legend)](https://npmjs.org/package/mapboxgl-legend)\n[![NPM](https://img.shields.io/npm/l/mapboxgl-legend)](https://npmjs.org/package/mapboxgl-legend)\n\nAdd a legend to a mapbox-gl map by parsing layer layout \u0026 paint expressions.\n\n![image](https://user-images.githubusercontent.com/12972543/116700430-0d338b80-a9c7-11eb-913f-70c884589dc0.png)\n\nProperties currently supported:\n\n- `*-color`\n- `*-radius`\n- `*-image`\n- `*-pattern`\n\nExpressions currently supported:\n\n- `case`\n- `match`\n- `interpolate`\n- `step`\n- literals\n\nThe legend works seamlessly with [MapLibre](https://maplibre.org/) as well.\n\n## Get started\n\nInstall npm package\n\n```bash\nnpm install mapboxgl-legend\n```\n\nAdd legend control to map\n\n```javascript\nimport LegendControl from 'mapboxgl-legend';\nimport 'mapboxgl-legend/dist/style.css';\n\nconst legend = new LegendControl();\nmap.addControl(legend, 'bottom-left');\n```\n\nAdd layers as usual, and the legend will be autogenerated\n\n```javascript\nmap.addLayer({\n  id: 'density',\n  type: 'circle',\n  source: 'demographic',\n  paint: {\n    'circle-radius': [\n      'interpolate', ['linear'],\n      ['to-number', ['get', 'density']],\n      100, 10,\n      200, 17,\n      500, 30,\n      1000, 50,\n      2000, 75\n    ],\n    'circle-color': [\n      'match',\n      ['get', 'ethnicity'],\n      'White', '#f1e8c8',\n      'Black', '#443722',\n      'Hispanic', '#aa9761',\n      'Asian', '#e8e59d',\n      /* other */ '#ccc'\n    ]\n  },\n});\n```\n\n## Options\n\nA few options can be passed on legend initialization.\n\n| option | type | default | description |\n| --- | --- | --- | --- |\n| minimized | Boolean, undefined | `undefined` | If set, a button toggles layer visibility. Initial value is set as this attribute |\n| collapsed | Boolean | `false` | Set legend panels collapsed on load |\n| toggler | Boolean, string[] | `false` | Add button to show and hide layers. Provide an array of layer ids to toggle them with this button |\n| highlight | Boolean | `false` | Add interactivity to legend items |\n| layers | Array[string, RegExp], Object | `undefined` | List of layers to be added. If undefined all layers will be added |\n| onToggle | Function | `undefined` | Set a callback function to a layer visibility change. Function receives as parameters the `layerId` that changed and its visibility (boolean) |\n\nThe layers option is an array of the layers' ids, or strings casted as regex that match the layers' ids. It can also be an object with keys being the layers' ids and values being an array of visible attributes, or `true` if all visible. For a fine grained control over layers, this object can also contain the same options `collapsed`, `toggler`, `attributes` and `onToggle`.\n\n```javascript\nconst legend = new LegendControl({\n  // Show all properties in selected layers\n  layers: ['population', 'areas', /sw-\\d/],\n  layers: {\n    // Show all properties in this layer\n    areas: true,\n    // Show only selected properties in this layer\n    population: ['circle-radius'], \n    // Fine grained options per layer\n    pois: {\n      collapsed: true,\n      toggler: false,\n      highlight: true,\n      attributes: ['circle-radius'],\n    }\n  },\n})\n```\n\nThere are also a few options that be defined as a per-layer basis using the style `metadata` object.\n\n| option | type | description |\n| --- | --- | --- |\n| name | String | Set the panel title name |\n| unit | String | Add a unit to all labels |\n| labels | Object | Map a value to a text that replaces it as a label |\n\nMetadata provides an extra layer of control by hiding items that have a label set to `false`, except on step expressions.\n\n```javascript\nmap.addLayer({\n  id: 'density',\n  type: 'circle',\n  source: 'demographic',\n  paint: { /* ... */ },\n  metadata: {\n    name: 'Population Density',\n    unit: 'k/km²',\n    labels: {\n      10: 'Custom label for value 10',\n      other: '\u003c 1k/km²',\n      an_item_to_hide: false,\n    }\n  }\n});\n```\n\nFor pairs labels, such as in `step` expressions, it is possible to labelize by using the serialized array of steps as a key\n\n```javascript\nmatadata: {\n  labels: {\n    '0,10': 'Group A',\n    '10,20': 'Group B',\n  },\n}\n```\n\n## Handle layers\n\nLayers can be added or removed from legend at any moment by using `legend.addLayers()` with same format as `layers` option and `legend.removeLayers([layerIds])`.\n\n## Styles\n\nLegend defaults to a simple design inspired by standard mapbox-gl controls, but can be tunned by changing CSS variables. Check default values in `/src/styles/_variables.scss`\n\n## Development\n\nCreate a `.env` file and set your Mapbox token as `VITE_MAPBOX_TOKEN`.\n\nRun the development server with the command\n\n```bash\nnpm run dev\n```\n\n## Contribute\n\nWhether you're fixing a bug, implementing a new feature, or improving the documentation, your contribution is greatly appreciated.\n\nStart by forking the repository on GitHub, create a new branch and finally submit a Pull Request with your changes. Provide a detailed description of your changes, including any relevant context or references to issues.\n\nBy contributing to this project, you agree that your contributions will be licensed under the ISC License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusand%2Fmapboxgl-legend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkusand%2Fmapboxgl-legend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusand%2Fmapboxgl-legend/lists"}