feat: New GeoClipPath component for clipping content to GeoJSON boundaries in both SVG and Canvas modes

techniq · techniq · commit 9b0267ddb86b · 2026-04-12T18:42:54.000-04:00
diff --git a/.changeset/add-geoclippath-component.md b/.changeset/add-geoclippath-component.md
@@ -0,0 +1,5 @@
+---
+'layerchart': minor
+---
+
+feat: New `GeoClipPath` component for clipping content to GeoJSON boundaries in both SVG and Canvas modes
diff --git a/docs/src/content/components/CircleClipPath.md b/docs/src/content/components/CircleClipPath.md
@@ -2,5 +2,5 @@
 description: Clipping component which conditionally applies a circular clip region to its child elements based on the rendering context and provided properties.
 category: clipping
 layers: [svg]
-related: []
+related: [ClipPath, GeoClipPath, RectClipPath]
 ---
diff --git a/docs/src/content/components/ClipPath.md b/docs/src/content/components/ClipPath.md
@@ -2,12 +2,6 @@
 description: Clipping component which defines a clipping region to constrain the rendering of chart elements within a specified shape or boundary.
 category: clipping
 layers: [svg]
-related:
-  [
-    components/ChartClipPath,
-    components/CircleClipPath,
-    components/RectClipPath,
-    components/Threshold
-  ]
+related: [ChartClipPath, CircleClipPath, GeoClipPath, RectClipPath, Threshold]
 order: 1
 ---
diff --git a/docs/src/content/components/GeoClipPath.md b/docs/src/content/components/GeoClipPath.md
@@ -0,0 +1,6 @@
+---
+description: Clipping component which defines a GeoJSON-based clip region to constrain the rendering of chart elements within geographic boundaries. Supports both SVG and Canvas rendering.
+category: clipping
+layers: [svg, canvas]
+related: [ClipPath, ChartClipPath, CircleClipPath, RectClipPath, GeoPath]
+---
diff --git a/docs/src/content/components/RectClipPath.md b/docs/src/content/components/RectClipPath.md
@@ -2,5 +2,5 @@
 description: Clipping component which defines a rectangular clip region  to constrain the rendering of chart elements within a specified shape or boundary.
 category: clipping
 layers: [svg]
-related: [ChartClipPath]
+related: [ChartClipPath, ClipPath, GeoClipPath]
 ---
diff --git a/docs/src/examples/catalog/GeoClipPath.json b/docs/src/examples/catalog/GeoClipPath.json
@@ -0,0 +1,68 @@
+{
+  "component": "GeoClipPath",
+  "examples": [
+    {
+      "name": "basic",
+      "title": "basic",
+      "path": "/docs/components/GeoClipPath/basic",
+      "components": [
+        {
+          "component": "Chart",
+          "lineNumber": 15,
+          "line": "<Chart"
+        },
+        {
+          "component": "Layer",
+          "lineNumber": 22,
+          "line": "<Layer>"
+        },
+        {
+          "component": "GeoClipPath",
+          "lineNumber": 23,
+          "line": "<GeoClipPath geojson={nation}>"
+        },
+        {
+          "component": "Graticule",
+          "lineNumber": 24,
+          "line": "<Graticule class=\"stroke-primary/30\" />"
+        },
+        {
+          "component": "GeoPath",
+          "lineNumber": 28,
+          "line": "<GeoPath geojson={feature} class=\"fill-none stroke-surface-content/20\" />"
+        }
+      ]
+    }
+  ],
+  "usage": [
+    {
+      "example": "basic",
+      "component": "GeoClipPath",
+      "path": "/docs/components/GeoClipPath/basic",
+      "lineNumber": 23,
+      "line": "<GeoClipPath geojson={nation}>"
+    },
+    {
+      "example": "timezones",
+      "component": "GeoPath",
+      "path": "/docs/components/GeoPath/timezones",
+      "lineNumber": 116,
+      "line": "<GeoClipPath geojson={countriesGeojson} disabled={!enableClip}>"
+    },
+    {
+      "example": "clipped",
+      "component": "GeoTile",
+      "path": "/docs/components/GeoTile/clipped",
+      "lineNumber": 44,
+      "line": "<GeoClipPath geojson={selectedFeature}>"
+    },
+    {
+      "example": "us-water-vapor",
+      "component": "Raster",
+      "path": "/docs/components/Raster/us-water-vapor",
+      "lineNumber": 37,
+      "line": "<GeoClipPath geojson={nation}>"
+    }
+  ],
+  "updatedAt": "2026-04-12T22:40:49.420Z"
+}
diff --git a/docs/src/examples/components/GeoClipPath/basic.svelte b/docs/src/examples/components/GeoClipPath/basic.svelte
@@ -0,0 +1,33 @@
+<script module lang="ts">
+	import { getUsStatesTopology } from '$lib/geo.remote.js';
+	const topology = await getUsStatesTopology();
+</script>
+
+<script lang="ts">
+	import { geoAlbersUsa } from 'd3-geo';
+	import { feature } from 'topojson-client';
+	import { Chart, GeoClipPath, GeoPath, Graticule, Layer } from 'layerchart';
+
+	const nation = feature(topology as any, (topology as any).objects.nation);
+	const states = feature(topology, topology.objects.states);
+</script>
+
+<Chart
+	geo={{
+		projection: geoAlbersUsa,
+		fitGeojson: states
+	}}
+	height={400}
+>
+	<Layer>
+		<GeoClipPath geojson={nation}>
+			<Graticule class="stroke-primary/30" />
+		</GeoClipPath>
+
+		{#each states.features as feature (feature.id)}
+			<GeoPath geojson={feature} class="fill-none stroke-surface-content/20" />
+		{/each}
+
+		<GeoPath geojson={nation} class="fill-none stroke-surface-content" />
+	</Layer>
+</Chart>
diff --git a/docs/src/examples/components/GeoPath/timezones.svelte b/docs/src/examples/components/GeoPath/timezones.svelte
@@ -22,7 +22,17 @@
 	// @ts-expect-error
 	import { century, equationOfTime, declination } from 'solar-calculator';
 
-	import { Blur, Chart, ClipPath, GeoCircle, GeoPath, Layer, Tooltip, antipode } from 'layerchart';
+	import {
+		Blur,
+		Chart,
+		ClipPath,
+		GeoCircle,
+		GeoClipPath,
+		GeoPath,
+		Layer,
+		Tooltip,
+		antipode
+	} from 'layerchart';
 	import TimezonesControls from '$lib/components/controls/GeoPathTimezonesControls.svelte';
 	import { TimerState } from '@layerstack/svelte-state';
 
@@ -103,8 +113,7 @@
 	<Layer>
 		<GeoPath geojson={{ type: 'Sphere' }} class="stroke-surface-content/30" id="globe" />
 
-		<GeoPath geojson={countriesGeojson} id="clip" />
-		<ClipPath useId="clip" disabled={!enableClip}>
+		<GeoClipPath geojson={countriesGeojson} disabled={!enableClip}>
 			{#each timezoneGeojson.features as feature}
 				<GeoPath
 					geojson={feature}
@@ -113,7 +122,7 @@
 					class="stroke-gray-900/50 hover:brightness-110"
 				/>
 			{/each}
-		</ClipPath>
+		</GeoClipPath>
 
 		{#each countriesGeojson.features as feature}
 			<GeoPath geojson={feature} class="stroke-gray-900/10 fill-gray-900/20 pointer-events-none" />
diff --git a/docs/src/examples/components/GeoTile/clipped.svelte b/docs/src/examples/components/GeoTile/clipped.svelte
@@ -8,7 +8,7 @@
 	import { geoMercator } from 'd3-geo';
 	import { feature } from 'topojson-client';
 
-	import { ClipPath, Chart, GeoPath, GeoTile, Layer, Tooltip } from 'layerchart';
+	import { Chart, GeoClipPath, GeoPath, GeoTile, Layer, Tooltip } from 'layerchart';
 	import GeoTileControls from '$lib/components/controls/GeoTileControls.svelte';
 	const states = feature(topology, topology.objects.states);
 
@@ -41,10 +41,9 @@
 >
 	{#snippet children({ context })}
 		<Layer>
-			<ClipPath useId="clip">
+			<GeoClipPath geojson={selectedFeature}>
 				<GeoTile url={serviceUrl} {zoomDelta} />
-			</ClipPath>
-			<GeoPath geojson={selectedFeature} id="clip" class="stroke-none" />
+			</GeoClipPath>
 			{#each filteredStates.features as feature}
 				<GeoPath
 					geojson={feature}
diff --git a/docs/src/examples/components/Raster/us-water-vapor.svelte b/docs/src/examples/components/Raster/us-water-vapor.svelte
@@ -3,7 +3,7 @@
 	import { interpolateRdYlBu } from 'd3-scale-chromatic';
 	import { geoAlbersUsa } from 'd3-geo';
 	import { feature } from 'topojson-client';
-	import { Chart, ClipPath, Contour, GeoPath, Layer, Legend, Raster } from 'layerchart';
+	import { Chart, Contour, GeoClipPath, GeoPath, Layer, Legend, Raster } from 'layerchart';
 
 	import { getWaterVapor } from '$lib/data.remote.js';
 	import { getUsCountiesTopology } from '$lib/geo.remote.js';
@@ -34,11 +34,7 @@
 	/>
 
 	<Layer>
-		<ClipPath>
-			{#snippet clip()}
-				<GeoPath geojson={nation} class="stroke-none" />
-			{/snippet}
-
+		<GeoClipPath geojson={nation}>
 			<Raster
 				data={waterVapor.values}
 				width={waterVapor.width}
@@ -64,7 +60,7 @@
 				thresholds={40}
 				blur={10}
 			/>
-		</ClipPath>
+		</GeoClipPath>
 
 		<GeoPath geojson={nation} class="fill-none stroke-[#2f2f2f]" strokeWidth={1.25} />
 	</Layer>
diff --git a/packages/layerchart/src/lib/components/ClipPath.svelte b/packages/layerchart/src/lib/components/ClipPath.svelte
@@ -84,7 +84,7 @@
             ctx.clip();
           }
         },
-        deps: () => canvasClipDeps?.() ?? [],
+        deps: () => [disabled, ...(canvasClipDeps?.() ?? [])],
       },
     });
   }
diff --git a/packages/layerchart/src/lib/components/GeoClipPath.svelte b/packages/layerchart/src/lib/components/GeoClipPath.svelte
@@ -0,0 +1,75 @@
+<script lang="ts" module>
+  import type { GeoPermissibleObjects } from 'd3-geo';
+  import type { Snippet } from 'svelte';
+
+  import type { ClipPathPropsWithoutHTML } from './ClipPath.svelte';
+  import type { GeoPathPropsWithoutHTML } from './GeoPath.svelte';
+  import type { Without } from '$lib/utils/types.js';
+
+  export type BaseGeoClipPathPropsWithoutHTML = {
+    /**
+     * A unique id for the clipPath.
+     */
+    id?: string;
+
+    /**
+     * GeoJSON data defining the clip boundary.
+     */
+    geojson: GeoPermissibleObjects;
+
+    /**
+     * Whether to disable clipping (show all).
+     *
+     * @default false
+     */
+    disabled?: boolean;
+
+    /**
+     * The children snippet to render content inside the clipPath.
+     */
+    children?: ClipPathPropsWithoutHTML['children'];
+  };
+
+  export type GeoClipPathPropsWithoutHTML = BaseGeoClipPathPropsWithoutHTML &
+    Without<GeoPathPropsWithoutHTML, BaseGeoClipPathPropsWithoutHTML>;
+
+  export type GeoClipPathProps = GeoClipPathPropsWithoutHTML;
+</script>
+
+<script lang="ts">
+  import { geoPath as d3GeoPath } from 'd3-geo';
+
+  import ClipPath from './ClipPath.svelte';
+  import GeoPath from './GeoPath.svelte';
+  import { createId } from '$lib/utils/createId.js';
+  import { extractLayerProps } from '$lib/utils/attributes.js';
+  import { getGeoContext } from '$lib/contexts/geo.js';
+
+  const uid = $props.id();
+
+  let {
+    id = createId('clipPath-', uid),
+    geojson,
+    disabled = false,
+    children,
+    ...restProps
+  }: GeoClipPathProps = $props();
+
+  const geo = getGeoContext();
+
+  function canvasClip(ctx: CanvasRenderingContext2D) {
+    if (!geo.projection || !geojson) return;
+    const pathGen = d3GeoPath(geo.projection, ctx);
+    pathGen(geojson);
+  }
+
+  function canvasClipDeps() {
+    return [geojson, geo.projection];
+  }
+</script>
+
+<ClipPath {id} {disabled} {children} {canvasClip} {canvasClipDeps}>
+  {#snippet clip()}
+    <GeoPath {geojson} class="stroke-none" {...extractLayerProps(restProps, 'lc-clip-path-geo')} />
+  {/snippet}
+</ClipPath>
diff --git a/packages/layerchart/src/lib/components/index.ts b/packages/layerchart/src/lib/components/index.ts
@@ -67,6 +67,8 @@ export { default as GeoProjection } from './GeoProjection.svelte';
 export * from './GeoProjection.svelte';
 export { default as GeoEdgeFade } from './GeoEdgeFade.svelte';
 export * from './GeoEdgeFade.svelte';
+export { default as GeoClipPath } from './GeoClipPath.svelte';
+export * from './GeoClipPath.svelte';
 export { default as GeoPath } from './GeoPath.svelte';
 export * from './GeoPath.svelte';
 export { default as GeoPoint } from './GeoPoint.svelte';

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'layerchart': minor
 +---
++
 +feat: New `GeoClipPath` component for clipping content to GeoJSON boundaries in both SVG and Canvas modes