# flatbush > Fast static spatial index for rectangles Latest version **4.6.2** (published 2026-06-09) · ISC license · 0 weekly downloads ## Install ```sh npm install flatbush pnpm add flatbush yarn add flatbush bun add flatbush ``` ## Health **Score 65/100 (B)** — status: active. Positive: has types; esm support; no vulnerabilities; high maintenance score; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 4.6.2 | | Published | 2026-06-09 | | First published | 2018-02-27 | | Weekly downloads | 0 | | License | ISC | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 1 | | Unpacked size | 52.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 1600 | | Author | Vladimir Agafonkin | | Maintainers | mourner | | Keywords | geometry, spatial, tree, index, rectangle, search | ## Links - npm: https://www.npmjs.com/package/flatbush - Repository: https://github.com/mourner/flatbush - Homepage: https://github.com/mourner/flatbush#readme - Issues: https://github.com/mourner/flatbush/issues - npm.io page: https://npm.io/package/flatbush ## Dependencies (1) - [flatqueue](https://npm.io/package/flatqueue.md) ^3.1.0 ## Alternatives - [jsforce](https://npm.io/package/jsforce.md) — 851.2K weekly downloads - [react-native-qrcode-svg](https://npm.io/package/react-native-qrcode-svg.md) — 693.5K weekly downloads - [@salesforce/plugin-data](https://npm.io/package/@salesforce/plugin-data.md) — 394.9K weekly downloads - [@backstage/plugin-search-common](https://npm.io/package/@backstage/plugin-search-common.md) — 308.5K weekly downloads - [@chain-registry/types](https://npm.io/package/@chain-registry/types.md) — 38.4K weekly downloads ## Recent versions - 4.6.2 (latest) — 2026-06-09 - 4.6.1 — 2026-06-09 - 4.6.0 — 2026-06-06 - 4.5.1 — 2026-03-13 - 4.5.0 — 2025-08-09 - 4.4.1 — 2025-07-05 - 4.4.0 — 2024-01-29 - 4.3.0 — 2024-01-20 - 4.2.0 — 2023-06-01 - 4.1.0 — 2023-04-10 - 4.0.0 — 2022-03-29 - 3.3.1 — 2022-03-28 - 3.3.0 — 2020-04-14 - 3.2.1 — 2020-03-18 - 3.2.0 — 2020-02-06 - … 16 more at https://npm.io/package/flatbush/versions ## README # Flatbush A really fast **static spatial index** for 2D points and rectangles in JavaScript. An efficient implementation of the [packed Hilbert R-tree](https://en.wikipedia.org/wiki/Hilbert_R-tree#Packed_Hilbert_R-trees) algorithm. Enables fast spatial queries on a very large number of objects (e.g. millions), which is very useful in maps, data visualizations and computational geometry algorithms. Similar to [RBush](https://github.com/mourner/rbush), with the following key differences: - **Static**: you can't add/remove items after initial indexing. - **Faster** indexing and search, with much lower **memory** footprint. - Index is stored as a single **array buffer** (to [transfer](https://developer.mozilla.org/en-US/docs/Glossary/Transferable_objects) between threads or save as a compact binary file). Supports geographic locations with the [geoflatbush](https://github.com/mourner/geoflatbush) extension. See also: [KDBush](https://github.com/mourner/kdbush), a similar library for points. [![Build Status](https://github.com/mourner/flatbush/actions/workflows/node.yml/badge.svg)](https://github.com/mourner/flatbush/actions) [![minzipped size](https://img.shields.io/bundlephobia/minzip/flatbush)](https://esm.run/flatbush) [![Simply Awesome](https://img.shields.io/badge/simply-awesome-brightgreen.svg)](https://github.com/mourner/projects) ## Usage ```js // initialize Flatbush for 1000 items const index = new Flatbush(1000); // fill it with 1000 rectangles for (const p of items) { index.add(p.minX, p.minY, p.maxX, p.maxY); } // perform the indexing index.finish(); // make a bounding box query const found = index.search(minX, minY, maxX, maxY).map((i) => items[i]); // make a k-nearest-neighbors query const neighborIds = index.neighbors(x, y, 5); // instantly transfer the index from a worker to the main thread postMessage(index.data, [index.data]); // reconstruct the index from a raw array buffer const index = Flatbush.from(e.data); ``` ## Install Install with NPM: `npm install flatbush`, then import as a module: ```js import Flatbush from 'flatbush'; ``` Or use as a module directly in the browser with [jsDelivr](https://www.jsdelivr.com/esm): ```html ``` Alternatively, there's a browser bundle with a `Flatbush` global variable: ```html ``` ## API #### `new Flatbush(numItems[, nodeSize, ArrayType, ArrayBufferType])` Creates a Flatbush index that will hold a given number of items (`numItems`). Additionally accepts: - `nodeSize`: size of the tree node (`16` by default); experiment with different values for best performance (increasing this value makes indexing faster and queries slower, and vise versa). - `ArrayType`: the array type used for coordinates storage (`Float64Array` by default); other types may be faster in certain cases (e.g. `Int32Array` when your data is integer). - `ArrayBufferType`: the array buffer type used to store data (`ArrayBuffer` by default); you may prefer `SharedArrayBuffer` if you want to share the index between threads (multiple `Worker`, `SharedWorker` or `ServiceWorker`). #### `index.add(minX, minY[, maxX, maxY])` Adds a given rectangle to the index. Returns a zero-based, incremental number that represents the newly added rectangle. If not provided, `maxX` and `maxY` default to `minX` and `minY` (essentially adding a point). #### `index.finish()` Performs indexing of the added rectangles. Their number must match the one provided when creating a `Flatbush` object. #### `index.search(minX, minY, maxX, maxY[, filterFn])` Returns an array of indices of items intersecting or touching a given bounding box. Item indices refer to the value returned by [`index.add()`](#indexaddminx-miny-maxx-maxy). ```js const ids = index.search(10, 10, 20, 20); ``` If given a `filterFn`, calls it on every found item (passing the item's index & bounding box coordinates) and only includes it if the function returned a truthy value. ```js const ids = index.search(10, 10, 20, 20, (i) => items[i].foo === 'bar'); ``` Alternatively, instead of using the array of indices returned by `search`, you can handle the results in the function: ```js index.search(10, 10, 20, 20, (i, x0, y0, x1, y1) => { console.log(`Item found: ${items[i]}, bbox: ${x0} ${y0} ${x1} ${y1}`); }) ``` #### `index.neighbors(x, y[, maxResults, maxDistance, filterFn])` Returns an array of item indices in order of distance from the given `x, y` (known as K nearest neighbors, or KNN). Item indices refer to the value returned by [`index.add()`](#indexaddminx-miny-maxx-maxy). ```js const ids = index.neighbors(10, 10, 5); // returns 5 ids ``` `maxResults` and `maxDistance` are `Infinity` by default. If given a `filterFn`, calls it on items that potentially belong to the results (passing the item's index) and only includes an item if the function returned a truthy value. Unlike `search`, it shouldn't be used for handling results. #### `Flatbush.from(data[, byteOffset])` Recreates a Flatbush index from raw `ArrayBuffer` or `SharedArrayBuffer` data (that's exposed as `index.data` on a previously indexed Flatbush instance). Very useful for transferring or sharing indices between threads or storing them in a file. ### Properties - `data`: array buffer that holds the index. - `minX`, `minY`, `maxX`, `maxY`: bounding box of the data. - `numItems`: number of stored items. - `nodeSize`: number of items in a node tree. - `ArrayType`: array type used for internal coordinates storage. - `IndexArrayType`: array type used for internal item indices storage. ## Performance Running `node bench.js` with Node v14: bench | flatbush | rbush --- | --- | --- index 1,000,000 rectangles | 273ms | 1143ms 1000 searches 10% | 575ms | 781ms 1000 searches 1% | 63ms | 155ms 1000 searches 0.01% | 6ms | 17ms 1000 searches of 100 neighbors | 24ms | 43ms 1 search of 1,000,000 neighbors | 133ms | 280ms 100,000 searches of 1 neighbor | 710ms | 1170ms ## Ports - [chusitoo/flatbush](https://github.com/chusitoo/flatbush) (C++ port) - [jbuckmccready/static_aabb2d_index](https://github.com/jbuckmccready/static_aabb2d_index) (Rust port) - [jbuckmccready/Flatbush](https://github.com/jbuckmccready/Flatbush) (C# port) - [bmharper/flatbush-python](https://github.com/bmharper/flatbush-python) (Python port) - [FlatGeobuf](https://github.com/flatgeobuf/flatgeobuf) (a geospatial format inspired by Flatbush) - [IMQS/flatbush](https://github.com/IMQS/flatbush) (C++ port, no longer maintained) - [msfstef/flatbush-dart](https://github.com/msfstef/flatbush-dart) (Dart port) - [kylebarron/geo-index](https://github.com/kylebarron/geo-index) (Rust port and Python bindings, with ABI compatibility to this library) - [kylebarron/literate-flatbush](https://github.com/kylebarron/literate-flatbush) (["literate"](https://en.wikipedia.org/wiki/Literate_programming) JS port that documents the internal algorithm) --- _Source: https://npm.io/package/flatbush · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._