Fuse.js

Lightweight fuzzy-search library. Zero dependencies.

# Live Demo

1 Insert your items

[
  {
      title: "Old Man's War",
      author: {
        firstName: "John",
        lastName: "Scalzi"
      }
  },
  {
      title: "The Lock Artist",
      author: {
        firstName: "Steve",
        lastName: "Hamilton"
      }
  },
  {
      title: "HTML5",
      author: {
        firstName: "Remy",
        lastName: "Sharp"
      }
  },
  {
      title: "Right Ho Jeeves",
      author: {
        firstName: "P.D",
        lastName: "Woodhouse"
      }
  },
  {
      title: "The Code of the Wooster",
      author: {
        firstName: "P.D",
        lastName: "Woodhouse"
      }
  },
  {
      title: "Thank You Jeeves",
      author: {
        firstName: "P.D",
        lastName: "Woodhouse"
      }
  },
  {
      title: "The DaVinci Code",
      author: {
        firstName: "Dan",
        lastName: "Brown"
      }
  },
  {
      title: "Angels & Demons",
      author: {
        firstName: "Dan",
        lastName: "Brown"
      }
  },
  {
      title: "The Silmarillion",
      author: {
        firstName: "J.R.R",
        lastName: "Tolkien"
      }
  },
  {
      title: "Syrup",
      author: {
        firstName: "Max",
        lastName: "Barry"
      }
  },
  {
      title: "The Lost Symbol",
      author: {
        firstName: "Dan",
        lastName: "Brown"
      }
  },
  {
      title: "The Book of Lies",
      author: {
        firstName: "Brad",
        lastName: "Meltzer"
      }
  },
  {
      title: "Lamb",
      author: {
        firstName: "Christopher",
        lastName: "Moore"
      }
  },
  {
      title: "Fool",
      author: {
        firstName: "Christopher",
        lastName: "Moore"
      }
  },
  {
      title: "Incompetence",
      author: {
        firstName: "Rob",
        lastName: "Grant"
      }
  },
  {
      title: "Fat",
      author: {
        firstName: "Rob",
        lastName: "Grant"
      }
  },
  {
      title: "Colony",
      author: {
        firstName: "Rob",
        lastName: "Grant"
      }
  },
  {
      title: "Backwards, Red Dwarf",
      author: {
        firstName: "Rob",
        lastName: "Grant"
      }
  },
  {
      title: "The Grand Design",
      author: {
        firstName: "Stephen",
        lastName: "Hawking"
      }
  },
  {
      title: "The Book of Samson",
      author: {
        firstName: "David",
        lastName: "Maine"
      }
  },
  {
      title: "The Preservationist",
      author: {
        firstName: "David",
        lastName: "Maine"
      }
  },
  {
      title: "Fallen",
      author: {
        firstName: "David",
        lastName: "Maine"
      }
  },
  {
      title: "Monster 1959",
      author: {
        firstName: "David",
        lastName: "Maine"
      }
  }
]

2 Set the options

Case sensitive Indicates whether comparisons should be case sensitive.

Include score Whether the score should be included in the result set. A score of 0 indicates a perfect match, while a score of 1 indicates a complete mismatch.

Include matches Whether the matches should be included in the result set. When true, each record in the result set will include the indices of the matched characters: indices: [start, end]. These can consequently be used for highlighting purposes.

Minimum character length When set to include matches, only the matches whose length exceeds this value will be returned. (For instance, if you want to ignore single character index returns, set to 2)

Sort Whether to sort the result list, by score.

Tokenize When true, the algorithm will search individual words and the full string, computing the final score as a function of both. In this case, the threshold, distance, and location are inconsequential for individual tokens, and are thus ignored.

Match all tokens When true, the result set will only include records that match all tokens. Will only work if tokenize is also true.

Find All Matches When true, the matching function will continue to the end of a search pattern even if a perfect match has already been located in the string.

ID The name of the identifier property. If specified, the returned result will be a list of the items' identifiers, otherwise it will be a list of the items. See example.

Keys
List of properties that will be searched. This supports nested properties, weighted search, searching in arrays of strings and objects

Location Determines approximately where in the text is the pattern expected to be found.

Threshold At what point does the match algorithm give up. A threshold of 0.0 requires a perfect match (of both letters and location), a threshold of 1.0 would match anything.

Distance Determines how close the match must be to the fuzzy location (specified by location). An exact letter match which is distance characters away from the fuzzy location would score as a complete mismatch. A distance of 0 requires the match be at the exact location specified, a distance of 1000 would require a perfect match to be within 800 characters of the location to be found using a threshold of 0.8.

Max pattern length The maximum length of the pattern. The longer the pattern (i.e. the search query), the more intensive the search operation will be. Whenever the pattern exceeds the maxPatternLength, an error will be thrown. Why is this important? Read this.

3 Search

Go ahead and spell your query incorrectly. That's the point of Fuse.js

Here's the JavaScript:

Your search results:

Search time:

# Install

CDN

Available on cdnjs (see the latest version on Github).

NPM

NPM is the recommended installation method. It pairs nicely with a CommonJS module bundler such as Webpack or Browserify.

# latest stable
$ npm install fuse.js

# Examples

Searching by ID

var books = [{
  'ISBN': 'A',
  'title': "Old Man's War",
  'author': 'John Scalzi'
}, {
  'ISBN': 'B',
  'title': 'The Lock Artist',
  'author': 'Steve Hamilton'
}]

var options = {
  keys: ['title', 'author'],
  id: 'ISBN'
}
var fuse = new Fuse(books, options)

fuse.search('old')

[
  "A"
]

Weighted search

var books = [{
  title: "Old Man's War fiction",
  author: 'John X',
  tags: ['war']
}, {
  title: 'Right Ho Jeeves',
  author: 'P.D. Mans',
  tags: ['fiction', 'war']
}]

var options = {
  keys: [{
    name: 'title',
    weight: 0.3
  }, {
    name: 'author',
    weight: 0.7
  }]
};
var fuse = new Fuse(books, options)

fuse.search('Man')

[{
  "title": "Right Ho Jeeves",
  "author": "P.D. Mans",
  "tags": ["fiction", "war"]
}, {
  "title": "Old Man's War fiction",
  "author": "John X",
  "tags": ["war"]
}]

Searching in arrays of strings

var books = [{
  'title': "Old Man's War",
  'author': 'John Scalzi',
  'tags': ['fiction']
}, {
  'title': 'The Lock Artist',
  'author': 'Steve',
  'tags': ['thriller']
}]

var options = {
  keys: ['author', 'tags']
};
var fuse = new Fuse(books, options)

fuse.search('tion')

[{
  "title": "Old Man's War",
  "author": "John Scalzi",
  "tags": ["fiction"]
}]

Searching in arrays of objects

var books = [{
  'title': "Old Man's War",
  'author': {
    'name': 'John Scalzi',
    'tags': [{
      value: 'American'
    }]
  }
}, {
  'title': 'The Lock Artist',
  'author': {
    'name': 'Steve Hamilton',
    'tags': [{
      value: 'English'
    }]
  }
}]

var options = {
  keys: ['author.tags.value'],
};
var fuse = new Fuse(books, options)

fuse.search('engsh')

[{
  "title": "The Lock Artist",
  "author": {
    "tags": [{
      "value": "English"
    }]
  }
}]

Using in TypeScript

// Requires --esModuleInterop compiler flag!
// import * as Fuse with '--allowSyntheticDefaultImport'
// or import Fuse = require('fuse.js') with neither
import Fuse from 'fuse.js';

type SimpleBookFuse = {
    title: string;
    author: {
        firstName: string;
        lastName: string;
    };
    tags: string[]
};

const books: SimpleBookFuse[] = [{
  'title': "Old Man's War",
  'author': {
    'firstName': 'John',
    'lastName': 'Scalzi'
  },
  'tags': ['fiction']
}, {
  'title': 'The Lock Artist',
  'author': {
    'firstName': 'Steve',
    'lastName': 'Hamilton'
  },
  'tags': ['thriller']
}]

const options: Fuse.FuseOptions<SimpleBookFuse> = {
  keys: ['author', 'tags'],
};
const fuse = new Fuse(books, options)

const results = fuse.search('tion')

[{
  "title": "The Lock Artist",
  "author": {
    "tags": [{
      "value": "English"
    }]
  }
}]

// IDE's will show full IntelliSense support
// for example when using
results[0].ti... => suggested to expand to title

# Support Fuse.js Development

Fuse.js an open source project. Maintaining and updating it takes up a good chunk of time, and there's still plenty of work to do. To be able to provide the project with the attention it deserves, I decided to experiment with sponsorship and/or support. If this works out, I can route the chunk of time that is usually spent on lucrative endeavors to this project.

If you are an individual user and have enjoyed the benefits of using Fuse.js, consider donating as a token of appreciation - like buying me coffee once in a while 🙂

Support on Patreon (recurring pledge)

Donate via PayPal (one time)

# Contact

Fuse.js is created and maintained by Kiro Risk.

# Hire Me

If you're in need of professional JavaScript help, shoot me an email at hello@kiro.me.

(I am currently only accepting requests for side gigs 🙂)