{"id":17559,"library":"d3-svg-annotation","title":"D3 SVG Annotation","description":"d3-svg-annotation is a D3.js module designed to streamline the process of adding various types of annotations to SVG-based data visualizations. It provides a flexible API for creating notes, connectors, and subjects directly on a D3-rendered chart, offering configurable styling, text wrapping, and dynamic positioning. The current stable version is 2.5.1. The package maintains a release cadence focused on addressing bugs and implementing minor feature enhancements, with significant breaking changes typically reserved for major version bumps. Its primary differentiation lies in its tight integration with the D3 ecosystem, providing a programmatic way to add rich context and explanations to complex charts without needing separate HTML overlays or manual SVG manipulation.","status":"active","version":"2.5.1","language":"javascript","source_language":"en","source_url":"https://github.com/susielu/d3-annotation","tags":["javascript","d3","d3-module","annotation","typescript"],"install":[{"cmd":"npm install d3-svg-annotation","lang":"bash","label":"npm"},{"cmd":"yarn add d3-svg-annotation","lang":"bash","label":"yarn"},{"cmd":"pnpm add d3-svg-annotation","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"d3-svg-annotation is a D3 module and requires the core D3 library to function. It leverages D3's selections, scales, and other utilities.","package":"d3","optional":false}],"imports":[{"note":"Since v1.6.0, the package supports ES modules. CommonJS users should access the `annotation` property, though direct named exports are preferred for modern Node.js/bundler environments.","wrong":"const annotation = require('d3-svg-annotation');","symbol":"annotation","correct":"import { annotation } from 'd3-svg-annotation';"},{"note":"TypeScript users can import type definitions for configuring various annotation properties, such as for different connector or subject types.","symbol":"AnnotationTypeSettings","correct":"import type { AnnotationTypeSettings } from 'd3-svg-annotation';"},{"note":"This type represents the function returned by the `annotation` factory, which is then used to render annotations onto a D3 selection.","symbol":"Annotation","correct":"import type { Annotation } from 'd3-svg-annotation';"}],"quickstart":{"code":"import * as d3 from 'd3';\nimport { annotation } from 'd3-svg-annotation';\n\nconst margin = { top: 20, right: 20, bottom: 30, left: 40 };\nconst width = 600 - margin.left - margin.right;\nconst height = 400 - margin.top - margin.bottom;\n\nconst svg = d3.select('body').append('svg')\n  .attr('width', width + margin.left + margin.right)\n  .attr('height', height + margin.top + margin.bottom)\n  .append('g')\n  .attr('transform', `translate(${margin.left},${margin.top})`);\n\nconst annotations = [\n  {\n    note: { label: \"An interesting data point\", title: \"Point A\" },\n    x: 100,\n    y: 150,\n    dy: 30,\n    dx: 30,\n    subject: { radius: 10, radiusPadding: 5 },\n    color: \"#E8336D\"\n  },\n  {\n    note: { label: \"This is another observation.\", title: \"Point B\", align: \"left\" },\n    x: 450,\n    y: 100,\n    dy: -50,\n    dx: -60,\n    subject: { width: 50, height: 20 },\n    type: annotation.annotationCalloutRect,\n    color: \"#007bff\"\n  }\n];\n\nconst makeAnnotations = annotation()\n  .type(annotation.annotationLabel)\n  .annotations(annotations);\n\nsvg\n  .append('g')\n  .attr('class', 'annotation-group')\n  .call(makeAnnotations);\n\n// Add some basic styling for visibility\nd3.select('body').append('style').text(`\n  .annotation-group path {\n    stroke-linejoin: round;\n    stroke-linecap: round;\n  }\n  .annotation-group text {\n    font-family: sans-serif;\n    font-size: 12px;\n  }\n  .annotation-note-label {\n    fill: currentColor;\n  }\n`);\n","lang":"typescript","description":"This example demonstrates how to set up a basic D3 SVG container, define annotation data points, configure the annotation generator, and render two different types of annotations on the SVG."},"warnings":[{"fix":"Remove any `<link>` tags or `@import` statements referencing `d3-annotation.css` when upgrading to v2.x. Adjust custom styling to use the library's API or direct CSS for SVG elements.","message":"Starting with v2.0.0, the `d3-annotation.css` stylesheet is no longer required or supported. Default styling is now built directly into the library, and custom styling can be applied programmatically using the `color` property or standard CSS overrides.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade to `d3-svg-annotation@2.3.2` or later to ensure complete and correct TypeScript type definitions for `notePadding`.","message":"TypeScript users on versions prior to 2.3.2 may encounter missing type definitions or incorrect IntelliSense for the `notePadding` property, particularly when configuring note objects within annotations.","severity":"gotcha","affected_versions":">=2.0.0 <2.3.2"},{"fix":"Verify the script loading order in your HTML: `<script src=\"path/to/d3.min.js\"></script><script src=\"path/to/d3-annotation.min.js\"></script>`.","message":"When using the minified or unminified JavaScript file directly (e.g., from CDN or local file inclusion), ensure that the D3 library is loaded *before* `d3-svg-annotation`. The library expects `d3` to be globally available.","severity":"gotcha","affected_versions":"<=2.5.1"},{"fix":"Always ensure D3 is a separate dependency and loaded correctly when using versions 1.14.0 or newer. This is typically handled automatically by bundlers like Webpack or Rollup when using NPM imports.","message":"Prior to v1.14.0, the build included D3 dependency files within `d3-annotation` itself. From v1.14.0 onwards, `d3-annotation` is 'slimmed down' and expects D3 to be provided by the consumer, aligning with other D3 modules.","severity":"gotcha","affected_versions":">=1.14.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"For script tags, ensure D3 loads first. For modules, use `import { annotation } from 'd3-svg-annotation';` and ensure `d3` is also imported or globally available.","cause":"The D3 library was not loaded or not correctly exposed globally before `d3-svg-annotation` was initialized, or `annotation` was not imported as a named export in an ES module environment.","error":"TypeError: d3.annotation is not a function"},{"fix":"Update `d3-svg-annotation` to version `2.3.2` or higher to resolve the missing type definition for `notePadding`.","cause":"This TypeScript error indicates that you are attempting to use the `notePadding` property with a version of `d3-svg-annotation` where its type definition is missing or incorrect.","error":"Property 'notePadding' does not exist on type 'Omit<Annotation, \"type\">'"},{"fix":"Upgrade `d3-svg-annotation` to version `1.17.0` or later to fix issues related to note label display and whitespace handling.","cause":"Earlier versions (prior to v1.17.0) had a bug where note labels starting with whitespace would not display correctly or would be omitted during word wrapping.","error":"Annotation note label not visible or improperly wrapped, especially with leading whitespace."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}