From 8eeb5fbd4446a55dc351b786cbec473911beff0e Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Mon, 12 Oct 2026 10:56:51 -0400
Subject: [PATCH] feat: support custom annotation label and mark snippets

---
 .changeset/annotation-snippets.md             |   5 +
 docs/src/content/components/AnnotationLine.md |  14 ++
 .../src/content/components/AnnotationPoint.md |   6 +
 .../src/content/components/AnnotationRange.md |   8 ++
 .../AnnotationLine/custom-label.svelte        |  31 +++++
 .../AnnotationLine/custom-line.svelte         |  22 +++
 .../AnnotationPoint/custom-marker.svelte      |  43 ++++++
 .../AnnotationRange/custom-label.svelte       |  39 ++++++
 .../AnnotationLine/AnnotationLine.base.svelte |  41 +++---
 .../AnnotationLine.shared.svelte.ts           |  17 ++-
 .../AnnotationPoint.base.svelte               |  56 +++++---
 .../AnnotationPoint.shared.svelte.ts          |  18 ++-
 .../AnnotationRange.base.svelte               |  38 ++++--
 .../AnnotationRange.shared.svelte.ts          |  18 ++-
 .../lib/components/Annotations.svelte.test.ts | 127 ++++++++++++++++++
 15 files changed, 425 insertions(+), 58 deletions(-)
 create mode 100644 .changeset/annotation-snippets.md
 create mode 100644 docs/src/examples/components/AnnotationLine/custom-label.svelte
 create mode 100644 docs/src/examples/components/AnnotationLine/custom-line.svelte
 create mode 100644 docs/src/examples/components/AnnotationPoint/custom-marker.svelte
 create mode 100644 docs/src/examples/components/AnnotationRange/custom-label.svelte
 create mode 100644 packages/layerchart/src/lib/components/Annotations.svelte.test.ts

diff --git a/.changeset/annotation-snippets.md b/.changeset/annotation-snippets.md
new file mode 100644
index 0000000000..6fdcd7ae0f
--- /dev/null
+++ b/.changeset/annotation-snippets.md
@@ -0,0 +1,5 @@
+---
+'layerchart': minor
+---
+
+feat(AnnotationLine|AnnotationPoint|AnnotationRange): Accept a `label` snippet and a mark snippet (`line`, `circle`, `rect`) to render custom markup
diff --git a/docs/src/content/components/AnnotationLine.md b/docs/src/content/components/AnnotationLine.md
index b610fcbec6..ecdd118a0a 100644
--- a/docs/src/content/components/AnnotationLine.md
+++ b/docs/src/content/components/AnnotationLine.md
@@ -8,3 +8,17 @@ related: [AnnotationPoint, AnnotationRange]
 ## Usage
 
 :example{ name="horizontal" showCode }
+
+## Customization
+
+### Custom label
+
+Pass a `label` snippet to render your own markup. It receives the resolved label `props` (`x`, `y`, `textAnchor`, `verticalAnchor`, …) to position it with.
+
+:example{ name="custom-label" showCode }
+
+### Custom line
+
+Pass a `line` snippet to draw the line yourself. It receives the resolved `x1`/`y1`/`x2`/`y2` (and `props.line`) to spread.
+
+:example{ name="custom-line" showCode }
diff --git a/docs/src/content/components/AnnotationPoint.md b/docs/src/content/components/AnnotationPoint.md
index 62b91b1186..561bad2767 100644
--- a/docs/src/content/components/AnnotationPoint.md
+++ b/docs/src/content/components/AnnotationPoint.md
@@ -15,6 +15,12 @@ Pass `link` (or `link={{ type: 'swoop', ... }}` etc.) to draw a `<Link>` from
 the ring edge to the label.
 :example{ name="link-callouts" }
 
+### Custom marker
+
+Pass a `circle` snippet to draw your own marker, and a `label` snippet for your own label. Each receives the resolved `props` to spread.
+
+:example{ name="custom-marker" showCode }
+
 ### Geo
 
 Inside a geo `<Chart>`, `x`/`y` are interpreted as `[lon, lat]` and projected directly.
diff --git a/docs/src/content/components/AnnotationRange.md b/docs/src/content/components/AnnotationRange.md
index 63e43421a5..a64d62d834 100644
--- a/docs/src/content/components/AnnotationRange.md
+++ b/docs/src/content/components/AnnotationRange.md
@@ -8,3 +8,11 @@ related: [AnnotationLine, AnnotationPoint]
 ## Usage
 
 :example{ name="vertical-with-pattern-range" showCode }
+
+## Customization
+
+### Custom label
+
+Pass a `label` snippet to render your own markup (and a `rect` snippet to draw the range yourself). Each receives the resolved `props` to position it with.
+
+:example{ name="custom-label" showCode }
diff --git a/docs/src/examples/components/AnnotationLine/custom-label.svelte b/docs/src/examples/components/AnnotationLine/custom-label.svelte
new file mode 100644
index 0000000000..9d035229d6
--- /dev/null
+++ b/docs/src/examples/components/AnnotationLine/custom-label.svelte
@@ -0,0 +1,31 @@
+<script module lang="ts">
+	import { getAppleStock } from '$lib/data.remote';
+	const data = await getAppleStock();
+</script>
+
+<script lang="ts">
+	import { AnnotationLine, Layer, LineChart } from 'layerchart';
+
+	export { data };
+</script>
+
+<LineChart {data} x="date" y="value" height={300} padding={{ top: 10, bottom: 20, left: 25 }}>
+	{#snippet aboveContext()}
+		<Layer type="html" class="pointer-events-none">
+			<AnnotationLine
+				y={500}
+				props={{ line: { dashArray: [2, 2], stroke: 'var(--color-danger)' } }}
+			>
+				{#snippet label({ props })}
+					<div
+						class="absolute -translate-x-full -translate-y-1/2 whitespace-nowrap rounded-full bg-danger px-2 py-0.5 text-xs font-medium text-danger-content shadow"
+						style:left="{props.x}px"
+						style:top="{props.y}px"
+					>
+						Max · $500
+					</div>
+				{/snippet}
+			</AnnotationLine>
+		</Layer>
+	{/snippet}
+</LineChart>
diff --git a/docs/src/examples/components/AnnotationLine/custom-line.svelte b/docs/src/examples/components/AnnotationLine/custom-line.svelte
new file mode 100644
index 0000000000..960199e33f
--- /dev/null
+++ b/docs/src/examples/components/AnnotationLine/custom-line.svelte
@@ -0,0 +1,22 @@
+<script module lang="ts">
+	import { getAppleStock } from '$lib/data.remote';
+	const data = await getAppleStock();
+</script>
+
+<script lang="ts">
+	import { AnnotationLine, Line, LineChart } from 'layerchart';
+
+	export { data };
+</script>
+
+<LineChart {data} x="date" y="value" height={300} padding={{ top: 10, bottom: 20, left: 25 }}>
+	{#snippet aboveMarks()}
+		<AnnotationLine y={400} label="Target" props={{ label: { fill: 'var(--color-danger)' } }}>
+			{#snippet line({ props })}
+				<!-- Halo keeps the rule legible where it crosses the series -->
+				<Line {...props} stroke="var(--color-surface-100)" strokeWidth={6} />
+				<Line {...props} stroke="var(--color-danger)" strokeWidth={2} dashArray={[6, 4]} />
+			{/snippet}
+		</AnnotationLine>
+	{/snippet}
+</LineChart>
diff --git a/docs/src/examples/components/AnnotationPoint/custom-marker.svelte b/docs/src/examples/components/AnnotationPoint/custom-marker.svelte
new file mode 100644
index 0000000000..61da004822
--- /dev/null
+++ b/docs/src/examples/components/AnnotationPoint/custom-marker.svelte
@@ -0,0 +1,43 @@
+<script module lang="ts">
+	import { getAppleStock } from '$lib/data.remote';
+	const data = await getAppleStock();
+</script>
+
+<script lang="ts">
+	import { AnnotationPoint, Circle, LineChart } from 'layerchart';
+
+	const annotations = [
+		{ x: new Date('June 29, 2007'), y: 121.89, label: 'iPhone' },
+		{ x: new Date('April 3, 2010'), y: 232.39, label: 'iPad' },
+		{ x: new Date('March 7, 2012'), y: 545.18, label: 'Apple TV' }
+	];
+
+	const r = 4;
+
+	export { data };
+</script>
+
+<LineChart {data} x="date" y="value" height={300} padding={{ top: 10, bottom: 20, left: 25 }}>
+	{#snippet aboveMarks()}
+		{#each annotations as annotation}
+			<AnnotationPoint
+				x={annotation.x}
+				y={annotation.y}
+				{r}
+				label={annotation.label}
+				labelPlacement="top"
+				labelYOffset={6}
+				props={{
+					label: {
+						class: 'fill-primary stroke-surface-100 stroke-[3px] [paint-order:stroke] font-semibold'
+					}
+				}}
+			>
+				{#snippet circle({ props })}
+					<Circle {...props} r={r + 4} class="fill-primary/20 stroke-primary" />
+					<Circle {...props} class="fill-primary stroke-surface-100" strokeWidth={2} />
+				{/snippet}
+			</AnnotationPoint>
+		{/each}
+	{/snippet}
+</LineChart>
diff --git a/docs/src/examples/components/AnnotationRange/custom-label.svelte b/docs/src/examples/components/AnnotationRange/custom-label.svelte
new file mode 100644
index 0000000000..b88d1e92e1
--- /dev/null
+++ b/docs/src/examples/components/AnnotationRange/custom-label.svelte
@@ -0,0 +1,39 @@
+<script module lang="ts">
+	import { getAppleStock } from '$lib/data.remote';
+	const data = await getAppleStock();
+</script>
+
+<script lang="ts">
+	import { AnnotationRange, Layer, LineChart, defaultChartPadding } from 'layerchart';
+
+	export { data };
+</script>
+
+<LineChart
+	{data}
+	x="date"
+	y="value"
+	height={300}
+	padding={defaultChartPadding({ left: 25, bottom: 15 })}
+>
+	{#snippet belowContext()}
+		<Layer type="html" class="pointer-events-none">
+			<AnnotationRange
+				x={[new Date('2010-01-01'), new Date('2010-12-31')]}
+				class="bg-primary/10"
+				labelPlacement="top"
+				labelYOffset={8}
+			>
+				{#snippet label({ props })}
+					<div
+						class="absolute -translate-x-1/2 whitespace-nowrap rounded-full bg-primary px-2 py-0.5 text-xs font-medium text-primary-content shadow"
+						style:left="{props.x}px"
+						style:top="{props.y}px"
+					>
+						Fiscal 2010
+					</div>
+				{/snippet}
+			</AnnotationRange>
+		</Layer>
+	{/snippet}
+</LineChart>
diff --git a/packages/layerchart/src/lib/components/AnnotationLine/AnnotationLine.base.svelte b/packages/layerchart/src/lib/components/AnnotationLine/AnnotationLine.base.svelte
index 14e52056ee..bc75e18d0f 100644
--- a/packages/layerchart/src/lib/components/AnnotationLine/AnnotationLine.base.svelte
+++ b/packages/layerchart/src/lib/components/AnnotationLine/AnnotationLine.base.svelte
@@ -13,6 +13,8 @@
 <script lang="ts">
   import { getChartContext } from '$lib/contexts/chart.js';
   import { cls } from '@layerstack/tailwind';
+  import type { LineProps } from '../Line/Line.shared.svelte.js';
+  import type { TextProps } from '../Text/Text.shared.svelte.js';
 
   let {
     Line,
@@ -25,6 +27,7 @@
     y2: y2Prop,
     seriesKey,
     label,
+    line: lineSnippet,
     labelPlacement = 'top-right',
     labelXOffset = 0,
     labelYOffset = 0,
@@ -153,24 +156,30 @@
       verticalAnchor,
     };
   });
+
+  const resolvedLineProps = $derived({
+    ...line,
+    ...props?.line,
+    class: cls('lc-annotation-line', props?.line?.class),
+  } as LineProps);
+
+  const resolvedLabelProps = $derived({
+    ...labelProps,
+    ...props?.label,
+    class: cls('lc-annotation-line-label', props?.label?.class),
+  } as TextProps);
 </script>
 
-<Line
-  x1={line.x1}
-  y1={line.y1}
-  x2={line.x2}
-  y2={line.y2}
-  {...props?.line}
-  class={cls('lc-annotation-line', props?.line?.class)}
-/>
-
-{#if label}
-  <Text
-    value={label}
-    {...labelProps}
-    {...props?.label}
-    class={cls('lc-annotation-line-label', props?.label?.class)}
-  />
+{#if lineSnippet}
+  {@render lineSnippet({ props: resolvedLineProps })}
+{:else}
+  <Line {...resolvedLineProps} />
+{/if}
+
+{#if typeof label === 'function'}
+  {@render label({ props: resolvedLabelProps })}
+{:else if label}
+  <Text value={label} {...resolvedLabelProps} />
 {/if}
 
 <style>
diff --git a/packages/layerchart/src/lib/components/AnnotationLine/AnnotationLine.shared.svelte.ts b/packages/layerchart/src/lib/components/AnnotationLine/AnnotationLine.shared.svelte.ts
index 70848d1f12..6f3bc9c0df 100644
--- a/packages/layerchart/src/lib/components/AnnotationLine/AnnotationLine.shared.svelte.ts
+++ b/packages/layerchart/src/lib/components/AnnotationLine/AnnotationLine.shared.svelte.ts
@@ -1,9 +1,11 @@
-import type { ComponentProps } from 'svelte';
+import type { ComponentProps, Snippet } from 'svelte';
 import type { SVGAttributes } from 'svelte/elements';
 import type { CommonStyleProps, Without } from '$lib/utils/types.js';
 import type { SingleDomainType } from '$lib/utils/scales.svelte.js';
 import type Line from '../Line/Line.svelte';
+import type { LineProps } from '../Line/Line.shared.svelte.js';
 import type Text from '../Text/Text.svelte';
+import type { TextProps } from '../Text/Text.shared.svelte.js';
 import type { Placement } from '../types.js';
 
 export type AnnotationLinePropsWithoutHTML = {
@@ -20,10 +22,21 @@ export type AnnotationLinePropsWithoutHTML = {
   y1?: SingleDomainType;
   x2?: SingleDomainType;
   y2?: SingleDomainType;
-  label?: string;
+  /**
+   * The label for the line.
+   *
+   * Can either be a string or a snippet to render custom content.
+   * The snippet receives spreadable props (position, anchors and `props.label`) to apply to the label.
+   */
+  label?: string | Snippet<[{ props: TextProps }]>;
   labelPlacement?: Placement;
   labelXOffset?: number;
   labelYOffset?: number;
+  /**
+   * A snippet to render your own line in place of the default `<Line>`.
+   * The snippet receives spreadable props (`x1`/`y1`/`x2`/`y2` and `props.line`).
+   */
+  line?: Snippet<[{ props: LineProps }]>;
   props?: {
     label?: Partial<ComponentProps<typeof Text>>;
     line?: Partial<ComponentProps<typeof Line>>;
diff --git a/packages/layerchart/src/lib/components/AnnotationPoint/AnnotationPoint.base.svelte b/packages/layerchart/src/lib/components/AnnotationPoint/AnnotationPoint.base.svelte
index 5cf9e3e4e3..4d09d7198c 100644
--- a/packages/layerchart/src/lib/components/AnnotationPoint/AnnotationPoint.base.svelte
+++ b/packages/layerchart/src/lib/components/AnnotationPoint/AnnotationPoint.base.svelte
@@ -23,6 +23,8 @@
   import { getPointLabelLayout } from '$lib/utils/labelPlacement.js';
   import { getPixelValue } from '../Text/Text.shared.svelte.js';
   import { cls } from '@layerstack/tailwind';
+  import type { CircleProps } from '../Circle/Circle.shared.svelte.js';
+  import type { TextProps } from '../Text/Text.shared.svelte.js';
 
   let {
     Circle,
@@ -41,6 +43,7 @@
     fontSize = 12,
     labelGap = 2,
     link,
+    circle,
     details,
     props,
   }: AnnotationPointBaseProps = $props();
@@ -122,7 +125,9 @@
   function onPointerMove(e: PointerEvent | MouseEvent | TouchEvent) {
     if (details) {
       e.stopPropagation();
-      ctx.tooltip.show(e, { annotation: { label, details } });
+      ctx.tooltip.show(e, {
+        annotation: { label: typeof label === 'string' ? label : undefined, details },
+      });
     }
   }
 
@@ -132,21 +137,33 @@
       ctx.tooltip.hide();
     }
   }
+
+  const resolvedCircleProps = $derived({
+    cx: point.x,
+    cy: point.y,
+    r,
+    onpointermove: onPointerMove,
+    onmousemove: onPointerMove,
+    ontouchmove: onPointerMove,
+    onpointerleave: onPointerLeave,
+    onmouseleave: onPointerLeave,
+    ontouchend: onPointerLeave,
+    ...props?.circle,
+    class: cls('lc-annotation-point', link && 'lc-annotation-point-ring', props?.circle?.class),
+  } as CircleProps);
+
+  const resolvedLabelProps = $derived({
+    ...labelProps,
+    ...props?.label,
+    class: cls('lc-annotation-point-label', props?.label?.class),
+  } as TextProps);
 </script>
 
-<Circle
-  cx={point.x}
-  cy={point.y}
-  {r}
-  onpointermove={onPointerMove}
-  onmousemove={onPointerMove}
-  ontouchmove={onPointerMove}
-  onpointerleave={onPointerLeave}
-  onmouseleave={onPointerLeave}
-  ontouchend={onPointerLeave}
-  {...props?.circle}
-  class={cls('lc-annotation-point', link && 'lc-annotation-point-ring', props?.circle?.class)}
-/>
+{#if circle}
+  {@render circle({ props: resolvedCircleProps })}
+{:else}
+  <Circle {...resolvedCircleProps} />
+{/if}
 
 {#if linkEndpoints && Link}
   <Link
@@ -163,13 +180,10 @@
   />
 {/if}
 
-{#if label}
-  <Text
-    value={label}
-    {...labelProps}
-    {...props?.label}
-    class={cls('lc-annotation-point-label', props?.label?.class)}
-  />
+{#if typeof label === 'function'}
+  {@render label({ props: resolvedLabelProps })}
+{:else if label}
+  <Text value={label} {...resolvedLabelProps} />
 {/if}
 
 <style>
diff --git a/packages/layerchart/src/lib/components/AnnotationPoint/AnnotationPoint.shared.svelte.ts b/packages/layerchart/src/lib/components/AnnotationPoint/AnnotationPoint.shared.svelte.ts
index a88877bcb4..c2a0d62c6d 100644
--- a/packages/layerchart/src/lib/components/AnnotationPoint/AnnotationPoint.shared.svelte.ts
+++ b/packages/layerchart/src/lib/components/AnnotationPoint/AnnotationPoint.shared.svelte.ts
@@ -1,10 +1,12 @@
-import type { ComponentProps } from 'svelte';
+import type { ComponentProps, Snippet } from 'svelte';
 import type { SVGAttributes } from 'svelte/elements';
 import type { CommonStyleProps, Without } from '$lib/utils/types.js';
 import type { SingleDomainType } from '$lib/utils/scales.svelte.js';
 import type Circle from '../Circle/Circle.svelte';
+import type { CircleProps } from '../Circle/Circle.shared.svelte.js';
 import type Link from '../Link/Link.svelte';
 import type Text from '../Text/Text.svelte';
+import type { TextProps } from '../Text/Text.shared.svelte.js';
 import type { Placement } from '../types.js';
 
 export type AnnotationPointPropsWithoutHTML = {
@@ -21,8 +23,13 @@ export type AnnotationPointPropsWithoutHTML = {
   seriesKey?: string;
   /** Radius of the circle */
   r?: number;
-  /** Label to display on circle */
-  label?: string;
+  /**
+   * Label to display on circle.
+   *
+   * Can either be a string or a snippet to render custom content.
+   * The snippet receives spreadable props (position, anchors and `props.label`) to apply to the label.
+   */
+  label?: string | Snippet<[{ props: TextProps }]>;
   /**
    * Where to place the label relative to the point. `'smart'` derives the
    * placement (text anchor + link direction) from the geometry between the
@@ -61,6 +68,11 @@ export type AnnotationPointPropsWithoutHTML = {
    * (e.g. `{ type: 'beveled', radius: 20 }`).
    */
   link?: boolean | Partial<ComponentProps<typeof Link>>;
+  /**
+   * A snippet to render your own marker in place of the default `<Circle>`.
+   * The snippet receives spreadable props (`cx`/`cy`/`r`, tooltip handlers and `props.circle`).
+   */
+  circle?: Snippet<[{ props: CircleProps }]>;
   /** Details (description, etc) useful to display in tooltip */
   details?: any;
   /** Classes for inner elements */
diff --git a/packages/layerchart/src/lib/components/AnnotationRange/AnnotationRange.base.svelte b/packages/layerchart/src/lib/components/AnnotationRange/AnnotationRange.base.svelte
index e612f00072..4b6214ee2d 100644
--- a/packages/layerchart/src/lib/components/AnnotationRange/AnnotationRange.base.svelte
+++ b/packages/layerchart/src/lib/components/AnnotationRange/AnnotationRange.base.svelte
@@ -16,6 +16,8 @@
   import { getChartContext } from '$lib/contexts/chart.js';
   import { isScaleBand } from '$lib/utils/scales.svelte.js';
   import { cls } from '@layerstack/tailwind';
+  import type { RectProps } from '../Rect/Rect.shared.svelte.js';
+  import type { TextProps } from '../Text/Text.shared.svelte.js';
 
   let {
     LinearGradient,
@@ -28,6 +30,7 @@
     class: className,
     gradient,
     pattern,
+    rect: rectSnippet,
     label,
     labelPlacement = 'center',
     labelXOffset = 0,
@@ -91,15 +94,25 @@
         ? 'end'
         : 'middle',
   });
+
+  const resolvedRectProps = $derived({
+    ...rect,
+    ...props?.rect,
+    fill,
+    class: cls('lc-annotation-range', props?.rect?.class, className),
+  } as RectProps);
+
+  const resolvedLabelProps = $derived({
+    ...labelProps,
+    ...props?.label,
+    class: cls('lc-annotation-range-label', props?.label?.class),
+  } as TextProps);
 </script>
 
-{#if fill || className}
-  <Rect
-    {...rect}
-    {...props?.rect}
-    {fill}
-    class={cls('lc-annotation-range', props?.rect?.class, className)}
-  />
+{#if rectSnippet}
+  {@render rectSnippet({ props: resolvedRectProps })}
+{:else if fill || className}
+  <Rect {...resolvedRectProps} />
 {/if}
 
 {#if gradient}
@@ -118,13 +131,10 @@
   </Pattern>
 {/if}
 
-{#if label}
-  <Text
-    value={label}
-    {...labelProps}
-    {...props?.label}
-    class={cls('lc-annotation-range-label', props?.label?.class)}
-  />
+{#if typeof label === 'function'}
+  {@render label({ props: resolvedLabelProps })}
+{:else if label}
+  <Text value={label} {...resolvedLabelProps} />
 {/if}
 
 <style>
diff --git a/packages/layerchart/src/lib/components/AnnotationRange/AnnotationRange.shared.svelte.ts b/packages/layerchart/src/lib/components/AnnotationRange/AnnotationRange.shared.svelte.ts
index 6c84941091..41b9ed77d3 100644
--- a/packages/layerchart/src/lib/components/AnnotationRange/AnnotationRange.shared.svelte.ts
+++ b/packages/layerchart/src/lib/components/AnnotationRange/AnnotationRange.shared.svelte.ts
@@ -1,11 +1,13 @@
-import type { ComponentProps } from 'svelte';
+import type { ComponentProps, Snippet } from 'svelte';
 import type { SVGAttributes } from 'svelte/elements';
 import type { CommonStyleProps, Without } from '$lib/utils/types.js';
 import type { SingleDomainType } from '$lib/utils/scales.svelte.js';
 import type LinearGradient from '../LinearGradient/LinearGradient.svelte';
 import type Pattern from '../Pattern/Pattern.svelte';
 import type Rect from '../Rect/Rect.svelte';
+import type { RectProps } from '../Rect/Rect.shared.svelte.js';
 import type Text from '../Text/Text.svelte';
+import type { TextProps } from '../Text/Text.shared.svelte.js';
 import type { Placement } from '../types.js';
 
 export type AnnotationRangePropsWithoutHTML = {
@@ -19,7 +21,13 @@ export type AnnotationRangePropsWithoutHTML = {
    * range spans two values, and which segment each end belongs to is ambiguous.
    */
   seriesKey?: string;
-  label?: string;
+  /**
+   * The label for the range.
+   *
+   * Can either be a string or a snippet to render custom content.
+   * The snippet receives spreadable props (position, anchors and `props.label`) to apply to the label.
+   */
+  label?: string | Snippet<[{ props: TextProps }]>;
   labelPlacement?: Placement;
   labelXOffset?: number;
   labelYOffset?: number;
@@ -27,6 +35,12 @@ export type AnnotationRangePropsWithoutHTML = {
   class?: string;
   gradient?: ComponentProps<typeof LinearGradient>;
   pattern?: ComponentProps<typeof Pattern>;
+  /**
+   * A snippet to render your own range in place of the default `<Rect>`.
+   * The snippet receives spreadable props (`x`/`y`/`width`/`height`, `fill`, `class` and `props.rect`).
+   * `gradient` / `pattern` fills are still drawn on their own.
+   */
+  rect?: Snippet<[{ props: RectProps }]>;
   props?: {
     label?: Partial<ComponentProps<typeof Text>>;
     rect?: Partial<ComponentProps<typeof Rect>>;
diff --git a/packages/layerchart/src/lib/components/Annotations.svelte.test.ts b/packages/layerchart/src/lib/components/Annotations.svelte.test.ts
new file mode 100644
index 0000000000..2c6a5ab68a
--- /dev/null
+++ b/packages/layerchart/src/lib/components/Annotations.svelte.test.ts
@@ -0,0 +1,127 @@
+import { createRawSnippet } from 'svelte';
+import { describe, expect, it, vi } from 'vitest';
+import { render } from 'vitest-browser-svelte';
+
+import TestHarness from '$lib/tests/TestHarness.svelte';
+import AnnotationLine from './AnnotationLine/AnnotationLine.svelte';
+import AnnotationPoint from './AnnotationPoint/AnnotationPoint.svelte';
+import AnnotationRange from './AnnotationRange/AnnotationRange.svelte';
+
+const chartProps = {
+  xDomain: [0, 100],
+  yDomain: [0, 100],
+  width: 200,
+  height: 100,
+  padding: { top: 0, right: 0, bottom: 0, left: 0 },
+};
+
+/** Renders a `<div>` carrying the snippet's props as data attributes, so tests can read them */
+function capture(name: string, keys: string[]) {
+  return createRawSnippet<[{ props: Record<string, any> }]>((args) => ({
+    render: () => {
+      const { props } = args();
+      const attrs = keys.map((k) => `data-${k.toLowerCase()}="${props[k]}"`).join(' ');
+      return `<div data-snippet="${name}" ${attrs}></div>`;
+    },
+  }));
+}
+
+async function snippet(name: string) {
+  return vi.waitFor(() => {
+    const el = document.querySelector<HTMLElement>(`[data-snippet="${name}"]`);
+    expect(el).not.toBeNull();
+    return el!.dataset;
+  });
+}
+
+describe('AnnotationLine', () => {
+  it('should render a `label` snippet with the resolved label props', async () => {
+    render(TestHarness, {
+      chartProps,
+      layer: 'html',
+      component: AnnotationLine,
+      componentProps: {
+        y: 50,
+        label: capture('label', ['x', 'y', 'textAnchor', 'verticalAnchor', 'class', 'value']),
+        props: { label: { class: 'custom' } },
+      },
+    });
+
+    // Horizontal rule, `top-right` placement: the right end of the line, anchored up and in
+    const label = await snippet('label');
+    expect(Number(label.x)).toBe(200);
+    expect(Number(label.y)).toBe(50);
+    expect(label.textanchor).toBe('end');
+    expect(label.verticalanchor).toBe('end');
+    expect(label.class).toContain('lc-annotation-line-label');
+    expect(label.class).toContain('custom');
+    // No text to put in the snippet's way
+    expect(label.value).toBe('undefined');
+    expect(document.querySelector('.lc-annotation-line-label')).toBeNull();
+  });
+
+  it('should render a `line` snippet in place of the default line', async () => {
+    render(TestHarness, {
+      chartProps,
+      layer: 'html',
+      component: AnnotationLine,
+      componentProps: {
+        x: 25,
+        line: capture('line', ['x1', 'y1', 'x2', 'y2', 'class']),
+      },
+    });
+
+    const line = await snippet('line');
+    expect([line.x1, line.y1, line.x2, line.y2].map(Number)).toEqual([50, 100, 50, 0]);
+    expect(line.class).toContain('lc-annotation-line');
+    expect(document.querySelector('.lc-annotation-line:not([data-snippet])')).toBeNull();
+  });
+});
+
+describe('AnnotationPoint', () => {
+  it('should render `circle` and `label` snippets with the resolved props', async () => {
+    render(TestHarness, {
+      chartProps,
+      layer: 'html',
+      component: AnnotationPoint,
+      componentProps: {
+        x: 50,
+        y: 50,
+        r: 6,
+        circle: capture('circle', ['cx', 'cy', 'r', 'class']),
+        label: capture('label', ['x', 'y', 'class']),
+      },
+    });
+
+    const circle = await snippet('circle');
+    expect([circle.cx, circle.cy, circle.r].map(Number)).toEqual([100, 50, 6]);
+    expect(circle.class).toContain('lc-annotation-point');
+
+    const label = await snippet('label');
+    expect([label.x, label.y].map(Number)).toEqual([100, 50]);
+    expect(label.class).toContain('lc-annotation-point-label');
+  });
+});
+
+describe('AnnotationRange', () => {
+  it('should render a `rect` snippet even without a `fill`', async () => {
+    render(TestHarness, {
+      chartProps,
+      layer: 'html',
+      component: AnnotationRange,
+      componentProps: {
+        x: [25, 75],
+        rect: capture('rect', ['x', 'y', 'width', 'height', 'class']),
+        label: capture('label', ['x', 'y']),
+      },
+    });
+
+    const rect = await snippet('rect');
+    expect([rect.x, rect.y, rect.width, rect.height].map(Number)).toEqual([50, 0, 100, 100]);
+    expect(rect.class).toContain('lc-annotation-range');
+
+    // `center` placement
+    const label = await snippet('label');
+    expect([label.x, label.y].map(Number)).toEqual([100, 50]);
+  });
+});