Earcut - Polygon Triangulation

3.0.2 · active · verified Tue Apr 21

Earcut is a JavaScript library designed for fast and lightweight polygon triangulation, primarily optimized for WebGL applications. The current stable version is 3.0.2. It aims to provide real-time triangulation performance in browsers by prioritizing raw speed and simplicity over guaranteed correctness for highly degenerate or self-intersecting polygons. It implements a modified ear slicing algorithm using z-order curve hashing, capable of handling holes, twisted polygons, degeneracies, and self-intersections. While it doesn't guarantee perfectly correct triangulation for all edge cases, it typically produces acceptable results for practical datasets. It differentiates itself from alternatives by its significant speed advantage, as evidenced by benchmarks, and was originally developed for Mapbox GL. Earcut is a 2D algorithm, and for 3D inputs, it processes data as if projected onto the XY plane, ignoring the Z-component.

Common errors

```
TypeError: earcut is not a function
```
cause Attempting to use `require('earcut')` in a CommonJS environment with Earcut v3.0.0+.

fix Update your import statement to `import earcut from 'earcut';` if using an ES module-aware environment, or revert to Earcut v2.2.4 for CommonJS compatibility.
```
ReferenceError: earcut is not defined
```
cause Accessing `earcut()` directly in a browser environment using a UMD bundle of Earcut v3.0.0+.

fix Access the main function via `earcut.default()` for UMD bundles of version 3.0.0 and later.
```
RangeError: Invalid array length
```
cause Providing an empty or malformed `vertices` array, or `holes` array with invalid indices that exceed the bounds of `vertices`.

fix Verify that `vertices` is a flat array of numbers `[x0, y0, x1, y1, ...]` and `holes` contains valid start indices within the `vertices` array for each inner ring.

Warnings

breaking Version 3.0.0 switched to publishing as an ES module, dropping direct CommonJS support. Existing `require()` statements will fail.
Fix: Migrate to ES module import syntax (`import earcut from 'earcut';`). If CommonJS compatibility is strictly required, pin to version 2.2.4 or earlier, or use a build tool that handles ESM to CJS transpilation.
breaking Version 3.0.0 adopted modern ES syntax, which dropped native support for Internet Explorer 11 (IE11).
Fix: If IE11 compatibility is necessary, you must transpile Earcut in your build process (e.g., using Babel) to an older ES target.
breaking For UMD browser bundles generated from v3.0.0 onwards, the main Earcut function is exposed as `earcut.default`.
Fix: When using the UMD bundle in a browser, access the triangulation function via `earcut.default()` instead of `earcut()`.
gotcha Earcut is a 2D triangulation algorithm. When provided with 3D coordinates, it processes only the X and Y components, completely ignoring the Z-component.
Fix: Ensure your input data is suitable for 2D projection, or if the Z-axis is critical, consider alternative 3D triangulation or meshing libraries.
gotcha Earcut prioritizes speed over guaranteed geometric correctness for highly complex, self-intersecting, or degenerate polygons. It might produce suboptimal or incorrect triangulations for such 'bad data'.
Fix: For applications requiring absolute geometric correctness on all inputs, especially highly pathological ones, consider more robust libraries like `libtess.js`, which implement different algorithms with stronger guarantees.

Install

npm install earcut npm
yarn add earcut yarn
pnpm add earcut pnpm

Imports

earcut
wrong:
```
const earcut = require('earcut');
```
correct:
```
import earcut from 'earcut';
```
Since v3.0.0, Earcut is published as an ES module and drops CommonJS support. Use `import` syntax for modern environments. For CommonJS compatibility, use version 2.2.4 or earlier.
earcut.flatten
```
import earcut from 'earcut';
const data = earcut.flatten([[0,0,1],[10,0,1],[10,10,1],[0,10,1]]);
```
The `flatten` utility is a static method on the default export, useful for converting multi-dimensional arrays (e.g., GeoJSON Polygon format) into the flat array format expected by `earcut`.
earcut in browser UMD
wrong:
```
const triangles = earcut([10,0, 0,50, 60,60, 70,10]);
```
correct:
```
const triangles = earcut.default([10,0, 0,50, 60,60, 70,10]);
```
For legacy UMD browser bundles (available in v3.0.0 and later), the main `earcut` function is exposed as `earcut.default` to align with ESM interoperability. Older UMD versions exposed it directly.

Quickstart

Demonstrates basic polygon triangulation for both simple shapes and those with holes, including how 3D vertex data is handled (Z-component ignored).

import earcut from 'earcut';

// Triangulate a simple polygon (e.g., a square)
const vertices = [0, 0, 100, 0, 100, 100, 0, 100];
const simpleTriangles = earcut(vertices);
console.log('Simple Polygon Triangles:', simpleTriangles);
// Expected: [1,0,3, 2,1,3]

// Triangulate a polygon with a hole
const polygonWithHoleVertices = [
  0,0, 100,0, 100,100, 0,100,  // Outer ring (4 vertices)
  20,20, 80,20, 80,80, 20,80   // Inner ring (4 vertices)
];
const holeIndices = [4]; // The hole starts at index 4 (5th vertex)
const holedTriangles = earcut(polygonWithHoleVertices, holeIndices);
console.log('Polygon with Hole Triangles:', holedTriangles);
// Expected: [3,0,4, 5,4,0, 3,4,7, 5,0,1, 2,3,7, 6,5,1, 2,7,6, 6,1,2]

// Example with 3D coordinates (Z-component is ignored)
const vertices3D = [10,0,1, 0,50,2, 60,60,3, 70,10,4];
const triangles3D = earcut(vertices3D, null, 3); // dimensions = 3
console.log('3D Input (Z ignored) Triangles:', triangles3D);
// Expected: [1,0,3, 3,2,1]

view raw JSON →