earcut

library1.1.5jsnpmunverified

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.

data

npm install earcut

github ↗package ↗

INSTALL

IMPORT

SIG · EARCUT

earcut

datajavascriptv1.1.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

earcut

✓ import earcut from 'earcut';

✗ const earcut = require('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

✓ const triangles = earcut.default([10,0, 0,50, 60,60, 70,10]);

✗ const triangles = earcut([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.

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]

Debug

Known issues

breakingVersion 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.

affects: >=3.0.0

breakingVersion 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.

affects: >=3.0.0

breakingFor 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()`.

affects: >=3.0.0

gotchaEarcut 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.

affects: all

gotchaEarcut 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.

affects: all

Errors

Common errors & fixes

TypeError: earcut is not a function

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

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

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.

Upgrade

Version history

1.1.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/mapbox/earcut ↗

packagehttps://www.npmjs.com/package/earcut ↗