Skip to Content
Menu

keywordFilter()

Allows real-time filtering of lists.

JavaScript February 7, 2021

Usage

JavaScript
nebula.keywordFilter(container, parent, values, filteredClass, operator);

Parameters

container
(Required) (Selector) The selector for the container element that wraps all individual elements.
Default: None

parent
(Required) (Selector) The selector of the parent element of the individual element to be searched/filtered.
Default: None

values
(Required) (String|Array) The text string, RegEx pattern, or array of strings to search for
Default: string

filteredClass
(Optional) (String) The class to add to non-matching items
Default: filtereditem

operator
(Optional) (String) When multiple values are used should this look for any ("or") or all ("and")?
Default: and

Parameter Notes

values parameter will commonly use jQuery(this).val().

To define your own custom regular expression for the “value” parameter, start and end the string with “/”. When using RegEx this way, only 1 parameter is accepted. However, each individual pattern accepts regular expression syntax. See examples below for details.

Request or provide clarification »

Examples

Simple input string filter

JavaScript
jQuery(document).on('keyup', '#example-input', function(){
    nebula.keywordFilter('ul#example-list', 'li', jQuery(this).val());
});

Custom RegEx pattern filter

JavaScript
nebula.keywordFilter('ul#example-list', 'li', '/custom|regex|pattern/');

Multiple RegEx patterns (with "or" operator)

JavaScript
nebula.keywordFilter('ul#example-list', 'li', ['custom|pattern', 'number\d+'], 'filtereditem', 'or');

Multiple strings (with "and" operator and custom filtered class)

JavaScript
nebula.keywordFilter('ul#example-list', 'li', ['lorem', 'ipsum', 'dolor'], 'hide-this', 'and');

Demo


Type a keyword into one or both inputs below to filter the list of items

Example List

  • Example 1

    This is the first example.

  • Another Example

    This is the second example.

  • Lorem ipsum dolor

    Duis dictum, turpis vitae mollis imperdiet.

  • Sed id orci volutpat

    Sed risus augue, semper et ornare a, placerat eu nibh.

  • Vestibulum mattis sapien

    Fusce sit amet varius eros.

  • Ut molestie quis

    Donec ex turpis, laoreet at felis

  • Fusce ornare felis

    Morbi hendrerit nibh sit amet aliquet

  • Vestibulum ante

    Lorem ipsum dolor sit amet

  • Quisque non ipsum

    Mauris molestie vestibulum imperdiet

  • Maecenas volutpat

    Vestibulum aliquet arcu molestie

  • Phasellus placerat

    Cras nec ante sed nisl

  • Curabitur a faucibus

    Aenean interdum ut purus

  • Nullam ut ligula

    Fusce consequat semper

  • Example 14

    This is the fourteenth example

  • Example 15

    This is the fifteenth example

  • Example 16

    This is the sixteenth example

Additional Notes

“Container” is the element that wraps all of the individual elements. Think of this as the boundary for the filter. In a list example, the “container” would be the UL.

“Parent” is each individual element that will be filtered. In a list example, the “parent” would be the “LI”.

Note, the function keywordSearch() is an alias of this function for legacy versions of Nebula.

Was this page helpful? Yes No


    A feedback message is required to submit this form.


    Please check that you have entered a valid email address.

    Enter your email address if you would like a response.

    Thank you for your feedback!

    Source File

    Located in /assets/js/modules/search.js on line 21.

    No Hooks

    This function does not have any filters or actions available. Request one?
    JavaScript
    nebula.keywordFilter = function(container, parent, values = 'string', filteredClass = 'filtereditem', operator = 'and'){
        if ( typeof values === 'string' ){
            values = [values];
        }
        values = values.filter(String); //Remove any empty values from the array
    
        jQuery(container).find(parent + '.' + filteredClass).removeClass(filteredClass); //Reset everything for a new search filter
    
        if ( values.length ){
            if ( values.length === 1 && values[0].length > 2 && values[0].charAt(0) === '/' && values[0].slice(-1) === '/' ){
                let regex = new RegExp(values[0].substring(1).slice(0, -1), 'i'); //Convert the string to RegEx after removing the first and last /
                jQuery(container).find(parent).each(async function(){ //Loop through each element to check against the regex pattern
                    await nebula.yield();
    
                    let elementText = jQuery(this).text().trim().replaceAll(/\s\s+/g, ' '); //Combine all interior text of the element into a single line and remove extra whitespace
                    jQuery(this).addClass(filteredClass);
                    if ( regex.test(elementText) ){
                        jQuery(this).removeClass(filteredClass);
                    }
                });
            } else if ( !operator || operator === 'and' || operator === 'all' ){ //Match only elements that contain all keywords (Default operator is And if not provided)
                jQuery.each(values, async function(index, value){ //Loop through the values to search for
                    await nebula.yield();
    
                    if ( value && value.trim().length ){ //If the value exists and is not empty
                        //Check if the value is a valid RegEx string
                        try {
                            var regex = new RegExp(value, 'i'); //Keep var here so variable can be used outside of the try/catch without erroring
                        } catch(error){ //This is an invalid RegEx pattern
                            return false; //Ignore this search
                        }
    
                        jQuery(container).find(parent).not('.' + filteredClass).each(function(){ //Now check elements that have not yet been filtered for this value
                            let elementText = jQuery(this).text().trim().replaceAll(/\s\s+/g, ' '); //Combine all interior text of the element into a single line and remove extra whitespace
                            if ( !regex.test(elementText) ){
                                jQuery(this).addClass(filteredClass);
                            }
                        });
                    }
                });
            } else { //Match elements that contains any keyword
                let pattern = '';
                jQuery.each(values, function(index, value){
                    if ( value.trim().length ){ //If the value is not empty, add it to the pattern
                        pattern += value + '|';
                    }
                });
                pattern = pattern.slice(0, -1); //Remove the last | character
    
                let regex = new RegExp(pattern, 'i');
                jQuery(container).find(parent).each(async function(){ //Loop through each element to check against the regex pattern
                    await nebula.yield();
    
                    let elementText = jQuery(this).text().trim().replaceAll(/\s\s+/g, ' '); //Combine all interior text of the element into a single line and remove extra whitespace
                    jQuery(this).addClass(filteredClass);
                    if ( regex.test(elementText) ){
                        jQuery(this).removeClass(filteredClass);
                    }
                });
            }
        }
    };
    

    Override

    To override or disable this JavaScript function, simply redeclare it with the exact same function name. Remember: Some functionality is conditionally loaded via dynamic imports, so if your function is not overriding properly, try listening for a DOM event (described below).

    JavaScript

    For non-module import functions:

    nebula.keywordFilter = function(container, parent, values, filteredClass, operator){
        //Write your own code here, leave it blank, or return false.
    }


    For dynamically imported module function overrides:

    jQuery(window).on('load', function(){
        nebula.keywordFilter = function(container, parent, values, filteredClass, operator){
            //Write your own code here, leave it blank, or return false.
        }
    });


    Custom Nebula DOM events do also exist, so you could also try the following if the Window Load listener does not work:

    jQuery(document).on('nebula_module_loaded', function(module){
        //Note that the module variable is also available to know which module specifically was imported
        if ( typeof nebula.keywordFilter === 'function' ){
            nebula.keywordFilter = function(container, parent, values, filteredClass, operator){
                //Write your own code here, leave it blank, or return false.
            }
    	}
    });