Fast and easy searching inside a page.
Holmes filters a list of elements based on the value of a input
in just ~13KB (5KB minified).
Installation
You can install holmes
with either npm
or bower
under the package name holmes.js
. For npm
that looks like this:
$ npm install --save holmes.js
After which you can add it in your page with i.e. browserify or loading the module in a different script tag.
You have to make sure that you have a css
rule for the class .hidden
that hides elements however you want. One option is to have this:
.hidden {
display: none;
}
but this could be any css
you want.
Usage
Simple example
holmes({
input: '.search input', // default: input[type=search]
find: '.results div' // querySelectorAll that matches each of the results individually
})
All options
holmes({
// queryselector for the input
input: '.search input',
// queryselector for element to search in
find: '.results article',
// (optional) text to show when no results
placeholder: 'no results',
class: {
// (optional) class to add to matched elements
visible: 'visible',
// (optional) class to add to non-matched elements
hidden: 'hidden'
},
// (optional) if true, this will refresh the content every search
dynamic: false,
// (optional) needs to be true if the input is a contenteditable field instead of a
contenteditable: false,
// (optional) in case you don't want to wait for DOMContentLoaded before starting Holmes:
instant: true,
// (optional) if you want to start searching after a certain amount of characters are typed
minCharacters: 5
});
Methods and members
For all of the methods you should initialise a new instance of holmes
like this:
var h = new holmes(options);
Then you can use the following methods:
.clear()
You can clear a holmes input programmatically, by using:
h.clear();
.count()
You can receive informations on what elements are visible, hidden and in total at any point:
h.count(); // {all: 41, hidden: 34, visible: 7}
.start()
Start an even listener for the specified options. Holmes always has .start()
running on initialisation.
h.start();
.stop()
Stops the current running event listener. Resolves a Promise when this has been completed.
h.stop();
h.start(); // could accidentally start too soon
h.stop().then(h.start); // might take a small time
.hidden
There's also a member .hidden
that gives the count without a function call:
console.log(h.hidden); // 34
.elements
All of the elements that holmes considers. There's also .elementsLength
.input
The input that holmes looks in. There's also the last search string as .searchString
.placeholder
The current placeholder (DOM Node).
.options
Shows the options chosen chosen for this instance of holmes. You can also set options like this after initialisation.
console.log(h.options); // specified options
note: setting options after it's running might require
h.stop().then(h.start)
Showcase
What | who | image |
---|---|---|
bullg.it | @haroenv | ![]() |
family.scss | @lukyvj | ![]() |
wikeo.be | @bistory | ![]() |
I'd love to find out how people use my project, let me know if you want to be featured!
Questions?
Compatible up to IE9.
Let me know on twitter: @haroenv.
Contributing
Contributions are always welcome! Here are some loose guidelines:
- use
feature branches
- don't make it slower
- explain why you want a feature
npm run doc
to recreate the documentation
But I don't bite, if you have any questions or insecurities, hit me up for example on gitter.
License
Apache 2.0