{"id":16396353,"url":"https://github.com/clhenrick/color-legend-element","last_synced_at":"2026-04-26T00:01:09.134Z","repository":{"id":42701102,"uuid":"433109622","full_name":"clhenrick/color-legend-element","owner":"clhenrick","description":"A custom element (web component) suitable for use as a legend in data visualizations","archived":false,"fork":false,"pushed_at":"2026-04-25T22:45:04.000Z","size":2937,"stargazers_count":82,"open_issues_count":5,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-25T23:32:01.923Z","etag":null,"topics":["custom-elements","d3","d3js","data-visualization","lit-element","web-components"],"latest_commit_sha":null,"homepage":"https://clhenrick.github.io/color-legend-element/","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/clhenrick.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":"2021-11-29T16:07:28.000Z","updated_at":"2026-04-25T22:42:00.000Z","dependencies_parsed_at":"2024-03-02T04:30:18.558Z","dependency_job_id":"c73b2853-a53a-47e0-a677-52823f86faab","html_url":"https://github.com/clhenrick/color-legend-element","commit_stats":{"total_commits":33,"total_committers":3,"mean_commits":11.0,"dds":"0.33333333333333337","last_synced_commit":"fd30fa77a7da39f835b86b4807087243d151adc1"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/clhenrick/color-legend-element","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clhenrick%2Fcolor-legend-element","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clhenrick%2Fcolor-legend-element/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clhenrick%2Fcolor-legend-element/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clhenrick%2Fcolor-legend-element/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clhenrick","download_url":"https://codeload.github.com/clhenrick/color-legend-element/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clhenrick%2Fcolor-legend-element/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32280981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["custom-elements","d3","d3js","data-visualization","lit-element","web-components"],"created_at":"2024-10-11T05:07:08.948Z","updated_at":"2026-04-26T00:01:09.097Z","avatar_url":"https://github.com/clhenrick.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Color Legend Element\n\n![Screenshot of color-legend-element](./docs-src/assets/color-legend-element.png)\n\n```html\n\u003ccolor-legend\n  titletext=\"Snowfall (cm)\"\n  scaletype=\"continuous\"\n  tickformat=\".0f\"\n  domain=\"[0, 100]\"\n  range='[\"#eff3ff\", \"#bdd7e7\", \"#6baed6\", \"#3182bd\", \"#08519c\"]'\n\u003e\n\u003c/color-legend\u003e\n```\n\nA [Custom Element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) suitable for use as a legend in data visualizations. Built with [Lit](https://lit.dev/) and [D3JS](https://d3js.org/).\n\n## Features\n\n- Render legends for continuous, log10, discrete, threshold, and categorical scales.\n- Uses `d3-scale`'s concept of a `domain` and a `range` for mapping values to visual marks.\n- Compatible with color interpolators from `d3-scale-chromatic`\n- Customizable via its [properties / attributes](#properties) and [CSS variables](#css-variables).\n- Framework and bundler not required, just add a `\u003cscript\u003e` tag and use it!\n- [Small bundle size](https://bundlephobia.com/package/color-legend-element): 27kb minified and 9kb gzipped.\n\n## Installation\n\n**NOTE:** the `\u003ccolor-legend\u003e` assumes D3JS is available as a _peer dependency._ At the very least this should include the following modules from the D3JS library: `d3-scale`, `d3-array`, `d3-format`, `d3-interpolate`, and possibly `d3-scale-chromatic` if using one of d3's color schemes.\n\nInstall via [npm](https://www.npmjs.com/package/color-legend-element):\n\n```bash\nnpm install color-legend-element\n```\n\nOr via [Yarn](https://yarnpkg.com/):\n\n```bash\nyarn add color-legend-element\n```\n\nYou may then `import` the `\u003ccolor-legend\u003e` in the desired ES Module:\n\n```js\nimport \"color-legend-element\";\n```\n\nTo use without a frontend build tool, add the `\u003ccolor-legend\u003e` via a `\u003cscript\u003e` tag in your HTML document.\n\n```html\n\u003cscript\n  type=\"module\"\n  src=\"color-legend-element/build/color-legend-element.js\"\n\u003e\u003c/script\u003e\n```\n\nIf you prefer to not use the ESM build, you may instead use the UMD build:\n\n```html\n\u003cscript src=\"color-legend-element/build/color-legend-element.umd.js\"\u003e\u003c/script\u003e\n```\n\n### Windows OS Install\n\nNote that Windows OS users may experience a problem with module bundlers where the D3JS dependencies are not found by the CLE. To work around this, it is recommended to be sure to use the ESM build:\n\n```js\nimport \"color-legend-element/build/color-legend-element.js\";\n```\n\n## Example Usage\n\nThe `\u003ccolor-legend\u003e` will render using its default settings as follows:\n\n```html\n\u003ccolor-legend\u003e\u003c/color-legend\u003e\n```\n\nIt may be customized by settings its properties and CSS variables (full list below).\n\nSee [the color-legend website](https://clhenrick.github.io/color-legend-element) for more examples of how to use the Color Legend Element.\n\n## Properties\n\nThe following table lists the Color Legend Element's properties, most of which have a corresponding HTML attribute. All attributes use a lowercase naming convention, so for example the property `scaleType` corresponds to the attribute `scaletype`. See [the color-legend website](https://clhenrick.github.io/color-legend-element) for examples of how these properties and attributes may be configured to customize the `\u003ccolor-legend\u003e`.\n\n| Property      | Type                      | Default Value          | Description                                                                                            | Has Attribute |\n| ------------- | ------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------- |\n| titleText     | string                    | \"Color Legend Element\" | The title text that displays at the top of the legend.                                                 | Yes           |\n| width         | number                    | 325                    | The width of the SVG or categorical legend div element.                                                | Yes           |\n| height        | number                    | 32                     | The height of the SVG element.                                                                         | Yes           |\n| marginTop     | number                    | 6                      | The spacing between the legend bar and top most extent of the SVG.                                     | Yes           |\n| marginRight   | number                    | 12                     | The spacing between the legend bar and right most extent of the SVG.                                   | Yes           |\n| marginBottom  | number                    | 16                     | The spacing between the legend bar and bottom most extent of the SVG.                                  | Yes           |\n| marginLeft    | number                    | 12                     | The spacing between the legend bar and left most extent of the SVG.                                    | Yes           |\n| scaleType     | ScaleType                 | \"continuous\"           | The type of legend to render (e.g. data classification scheme the legend represents).                  | Yes           |\n| domain        | (number \\| string)[]      | `[0, 1]`               | The color scale's domain values.                                                                       | Yes           |\n| range         | string[]                  | `d3.schemeYlGnBu[5]`   | The color scale's range values.                                                                        | Yes           |\n| markType      | MarkType                  | \"circle\"               | The symbology used for categorical legends.                                                            | Yes           |\n| ticks         | number                    | 5                      | The desired number of axis ticks.                                                                      | Yes           |\n| tickFormat    | string                    | \".1f\"                  | The d3-format specifier to format axis tick values.                                                    | Yes           |\n| tickFormatter | (value: number) =\u003e string | `d3.format(\".1f\")`     | A function that handles formatting the tick values.                                                    | No            |\n| tickSize      | number                    | 6                      | The size or length of the axis ticks.                                                                  | Yes           |\n| tickValues    | number[]                  | `undefined`            | The explicit values to be used for axis ticks.                                                         | Yes           |\n| interpolator  | Interpolator              | `d3.interpolateHcl`    | The color interpolator function to use from [`d3-interpolate`](https://d3js.org/d3-interpolate/color). | No            |\n\nNotes on the above properties:\n\n- See [src/types.ts](./src/types.ts) for type definitions of `ScaleType`, `MarkType`, and `Interpolator`.\n\n- If the `tickFormatter` property is not explicitly set, it will be set internally using the value of `tickFormat` by passing the `tickFormat` string to [`d3.format`](https://d3js.org/d3-format).\n\n- The properties `tickFormat` and `tickFormatter` cannot be used simultaneously, they are both mechanisms for formatting the axis tick text. Setting the `tickFormatter` property explicitly will override the value of `tickFormat`, if it was previously set.\n\n## CSS Variables\n\nThe internal styling (CSS) of the Color Legend Element may be altered via the following [CSS variables / custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties):\n\n| Custom Property            | Default Value          | Description                                                             |\n| -------------------------- | ---------------------- | ----------------------------------------------------------------------- |\n| --cle-font-family          | sans-serif             | Font used for tick and legend item text                                 |\n| --cle-font-family-title    | var(--cle-font-family) | Font used for the legend's title text                                   |\n| --cle-font-size            | 0.75rem                | Font size for the tick and legend item text                             |\n| --cle-font-size-title      | 0.875rem               | Font size for the legend title text                                     |\n| --cle-letter-spacing       | 0.3px                  | Letter spacing for tick and legend item text                            |\n| --cle-letter-spacing-title | 0.25px                 | Letter spacing for the legend title text                                |\n| --cle-font-weight          | 400                    | Font weight for the tick and legend item text                           |\n| --cle-font-weight-title    | 500                    | Font weight for the title text                                          |\n| --cle-color                | currentColor           | Font color for all text and tick lines                                  |\n| --cle-background           | #fff                   | Background color for the legend                                         |\n| --cle-padding              | 0.375rem               | Padding in the legend's container div                                   |\n| --cle-border               | none                   | Border style of the legend's container div                              |\n| --cle-border-radius        | 0                      | Border radius of the legend's container div                             |\n| --cle-box-sizing           | content-box            | Box-sizing property of the legend's container div                       |\n| --cle-columns              | 2                      | Number of columns for categorical legends                               |\n| --cle-column-width         | auto                   | Column width for categorical legends                                    |\n| --cle-item-margin          | 0.375rem 0.75rem 0 0   | Margin property for categorical legend items                            |\n| --cle-line-width           | 24px                   | Width of the \"line\" markType for categorical legends                    |\n| --cle-line-height          | 2px                    | Height of the \"line\" markType for categorical legends                   |\n| --cle-swatch-size          | 10px                   | Height \u0026 Width of \"rect\" and \"circle\" markTypes for categorical legends |\n| --cle-swatch-width         | var(--cle-swatch-size) | Width of the \"rect\" and \"circle\" markTypes for categorical legends      |\n| --cle-swatch-height        | var(--cle-swatch-size) | Height of the \"rect\" and \"circle\" markTypes for categorical legends     |\n| --cle-swatch-margin        | 0 0.5rem 0 0           | Margin of the mark (line, square, circle) for categorical legends       |\n\nThe following example demonstrates how to override the default values of the `\u003ccolor-legend\u003e`'s CSS variables:\n\n```css\ncolor-legend {\n  --cle-font-family: serif;\n  --cle-font-family-title: Impact;\n  --cle-letter-spacing-title: 0.5px;\n  --cle-color: white;\n  --cle-background: #222;\n  --cle-border-radius: 6px;\n  --cle-padding: 0.25rem 0.25rem 0.75rem;\n}\n```\n\n## Local Development\n\nRequires Node.js v16.13.0 and NPM \u003e=8.\n\nIn the root of this repository first install dependencies:\n\n```bash\nnpm install\n```\n\n### Building from src\n\nAll compiled files will be outputted in the `build/` directory.\n\nTo create the ESM build:\n\n```bash\nnpm run build\n```\n\nor to watch for changes:\n\n```bash\nnpm run build:watch\n```\n\nTo create both the ESM \u0026 UMD bundles:\n\n```bash\nnpm run bundle\n```\n\n### Develop\n\nTo view the `\u003ccolor-legend\u003e` without bundling it:\n\n```\nnpm run serve\n```\n\nor\n\n```\nnpm run serve:prod\n```\n\nThis will start up a local web server for `dev/index.html`. You may then modify the contents of `src/` and/or `dev/index.html` and inspect the changes in your browser.\n\n### Running tests\n\nTests are located in [`src/test`](./src/test) and may be run in either a development or production environment via:\n\n```\nnpm run test:dev\n```\n\nor:\n\n```\nnpm run test:prod\n```\n\nTo run tests in both a development and a production environment do:\n\n```\nnpm run test\n```\n\nTo have the tests run when making changes to `src/`:\n\n```\nnpm run test:watch\n```\n\nor\n\n```\nnpm run test:prod:watch\n```\n\n### Building the docs\n\nTo generate the `docs` directory:\n\n```bash\nnpm run docs\n```\n\nThis will first remove the `docs/` directory, build files from the `src/`, and build files from the `docs-src/` directory into the `docs/` directory. All necessary files will be copied into `docs/` directory (e.g. from `build/` and `node_modules/`) in order for the `\u003ccolor-legend\u003e` render as it would in a production environment.\n\nTo serve the docs directory and watch for changes:\n\n```bash\nnpm run docs:serve\n```\n\nThen open your browser to `localhost:8080` to view the site.\n\n### Updating the custom-elements.json\n\nAccording to [Open Web Components](https://github.com/open-wc/custom-elements-manifest#custom-elements-manifest):\n\n\u003e Custom Elements Manifest is a file format that describes custom elements. This format will allow tooling and IDEs to give rich information about the custom elements in a given project.\n\nTo update the `custom-elements.json` manifest:\n\n```bash\nnpm run analyze\n```\n\n## License\n\nLicensed under the MIT License, Copyright 2021 Chris L Henrick.\n\n## Credits\n\n🙏 Some project boilerplate has been borrowed from the [Lit Element TypeScript Starter Kit](https://github.com/lit/lit-element-starter-ts) under the BSD-3-Clause License, Copyright 2017 Google LLC.\n\n🙏 Inspired by the [Color Legend](https://observablehq.com/@d3/color-legend) on [Observable](https://observablehq.com) by [Mike Bostock](https://observablehq.com/@mbostock) under the ISC License, Copyright 2019–2020 Observable, Inc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclhenrick%2Fcolor-legend-element","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclhenrick%2Fcolor-legend-element","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclhenrick%2Fcolor-legend-element/lists"}