How to Use match-sorter for Powerful Array Searches in JavaScript

Basic Usage of match-sorter

match-sorter is an npm‑published JavaScript library that simplifies searching within complex arrays and sorts results by relevance.

Installation

npm install --save match-sorter

Simple Example

Given a simple list:

const list = ['hi', 'hey', 'hello', 'sup', 'yo'];
matchSorter(list, 'y');

The call returns ['yo', 'hey'], because "yo" matches the query with higher relevance (the first character matches).

Working with Complex Objects

Consider the following array of objects:

const foods = [
  { IceCream: ['mint', 'chocolate'], Fruit: 'banana' },
  { IceCream: ['candy', 'brownie'], Fruit: 'apple' },
  { IceCream: ['cake', 'strawberry'], Fruit: 'orange' }
];

1) Find items where IceCream contains "ca"

var result = matchSorter(foods, 'ca', { keys: ['IceCream'] });
console.log(result);
// => [
//   { IceCream: ['candy', 'brownie'], Fruit: 'apple' },
//   { IceCream: ['cake', 'strawberry'], Fruit: 'orange' },
//   { IceCream: ['mint', 'chocolate'], Fruit: 'banana' }
// ]

The keys option tells match-sorter which property to search.

2) Find items where Fruit starts with "app"

var result = matchSorter(foods, 'app', {
  keys: ['Fruit'],
  threshold: matchSorter.rankings.STARTS_WITH
});
console.log(result);
// => [{ IceCream: ['candy', 'brownie'], Fruit: 'apple' }]

The threshold option specifies the matching mode; STARTS_WITH matches values that begin with the query.

3) Find items where IceCream exactly matches "mint"

var result = matchSorter(foods, 'mint', {
  keys: ['IceCream'],
  threshold: matchSorter.rankings.EQUALS
});
console.log(result);
// => [{ IceCream: ['mint', 'chocolate'], Fruit: 'banana' }]

Using EQUALS forces an exact match.

Searching Nested Keys

For objects with nested properties, specify the path in keys:

const nestedObjList = [
  { name: { first: 'Janice' } },
  { name: { first: 'Fred' } },
  { name: { first: 'George' } },
  { name: { first: 'Jen' } }
];
matchSorter(nestedObjList, 'j', { keys: ['name.first'] });
// => matches Janice, Jen

Available Matching Modes

EQUALS : exact match

STARTS_WITH : value begins with the query

WORD_STARTS_WITH : any word in the value starts with the query

CONTAINS : value contains the query anywhere

ACRONYM : matches the initials of words

These modes let you fine‑tune how match-sorter ranks results in large datasets.

Project repository: https://github.com/kentcdodds/match-sorter