Textbox Filter Control

Textbox filter control is used to filter content by the specified CSS selector.

See the Pen jPList Textbox Filter Control by 1rosehip (@1rosehip) on CodePen.

HTML Structure

Textbox filter control is defined by required data-jplist-control="textbox-filter" data attribute. The data-group attribute defines group of elements that should be filtered. The full list of data attributes can be found here.

<!-- jplist styles - should not be added if bootstrap or other CSS framework is used -->
<link href="jplist.styles.css" rel="stylesheet" type="text/css" />
                
<!-- text filter control -->
<input
     data-jplist-control="textbox-filter"
     data-group="group1"
     data-name="my-filter-1"
     data-path=".title"
     type="text"
     value=""
     placeholder="Filter by Title"
/>

<!-- content to filter -->
<div data-jplist-group="group1">

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

</div>

<!-- jplist library -->
<script src="jplist.min.js"></script>
<script>
    jplist.init();
</script>

Textbox with clear button

Clear button can be added using data-clear-btn-id data attribute that points to the button element:

<input
     data-jplist-control="textbox-filter"
     data-group="group1"
     data-name="my-filter-1"
     data-path=".title"
     data-clear-btn-id="title-clear-btn"
     type="text"
     value=""
     placeholder="Filter by Title"
/>
                
<button type="button" id="title-clear-btn">Clear</button>

Top and bottom panels

Textbox filter control can be placed in both top and bottom panels for the better user experience. In this case data-name attribute with the same value should be added. All other data attributes should also have the same values:

<!-- textbox filter control in the top panel -->
<input
     data-jplist-control="textbox-filter"
     data-group="group1"
     data-name="title-text-filter"
     data-path=".title"
     type="text"
     value=""
     placeholder="Filter by Title"
/>

<!-- content to filter -->
<div data-jplist-group="group1">

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

</div>

<!-- textbox filter control in the bottom panel -->
<input
     data-jplist-control="textbox-filter"
     data-group="group1"
     data-name="title-text-filter"
     data-path=".title"
     type="text"
     value=""
     placeholder="Filter by Title"
/>

Jump to top

data-jump data attribute can be used to scroll page to the specified location when user changes textbox value. data-jump="top" scrolls page to the top. Any CSS selector can be used instead of top keyword.

<input
     data-jplist-control="textbox-filter"
     data-group="group1"
     data-name="title-text-filter"
     data-path=".title"
     type="text"
     value=""
     placeholder="Filter by Title"
     data-jump="top"
/>

Deep Linking

Deep links can be used to keep user changes and control state after the page refresh. To implement them data-id attribute should be added to HTML structure and deepLinking setting should be true in jPList parameters.

In the example below deep link may look like http://www.example.com/page#group=group1&title=a where group1 is taken from data-jplist-group="group1", title is data-id value and a is current user input.

<!-- jplist styles - should not be added if bootstrap or other CSS framework is used -->
<link href="jplist.styles.css" rel="stylesheet" type="text/css" />

<!-- textbox filter control -->
<input
     data-jplist-control="textbox-filter"
     data-group="group1"
     data-name="title-text-filter"
     data-path=".title"
     type="text"
     value=""
     placeholder="Filter by Title"
     data-id="title"
/>

<!-- content to filter -->
<div data-jplist-group="group1">

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

</div>

<!-- jplist library -->
<script src="jplist.min.js"></script>
<script>
    jplist.init({
        deepLinking: true
    });
</script>

Storage

Local storage, session storage or cookies can be used to keep user selections and control states after the page refresh. To implement them data-id attribute should be added to HTML structure and storage setting should be passed to jPList constructor.

<!-- jplist styles - should not be added if bootstrap or other CSS framework is used -->
<link href="jplist.styles.css" rel="stylesheet" type="text/css" />

<!-- textbox filter control -->
<input
     data-jplist-control="textbox-filter"
     data-group="group1"
     data-name="title-text-filter"
     data-path=".title"
     type="text"
     value=""
     placeholder="Filter by Title"
     data-id="title"
/>

<!-- content to filter -->
<div data-jplist-group="group1">

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

    <!-- item -->
    <div data-jplist-item>
        <div class="title">Title value 1</div>
        ....
    </div>

</div>

<!-- jplist library -->
<script src="jplist.min.js"></script>
<script>
    jplist.init({
        storage: 'localStorage', //'localStorage', 'sessionStorage' or 'cookies'
        storageName: 'jplist'
    });
</script>

Ignore Special Characters

To ignore some characters during the search data-regex attribute can be use like in the example below. Here all names defined with underscore character instead of a space, for example Alejandro_Miles. To allow the user search for Alejandro Miles with space instead we may use the regex data-regex="[^a-zA-Z0-9]+" that ignores all characters except English letters and numbers.

See the Pen jPList Textbox Ignore Characters by 1rosehip (@1rosehip) on CodePen.

Data Attributes

The full list of control data attributes.

Name	Description	Values
`data-jplist-control`	Defines textbox filter control.	"textbox-filter"
`data-group`	Defines group of items that should be filtered. For example, if a control has data-group="group1" then items group should have data-jplist-group="group1" data attribute.	any text value
`data-name`	The data-name attribute is used to identify the same controls in different panels. Different controls should have different data-name attributes. By default, data-name attribute has default value.	any text value
`data-path`	CSS selector that defines the HTML element that should be filtered	"default" keyword for the initial value or anyCSS selector
`data-clear-btn-id`	The ID of the clear button element.	ID of the button
`data-jump`	This data attribute can be used to scroll page to the specified location when user changes a textbox value. data-jump="top" scrolls page to the top. Any CSS selector can be used instead of top keyword.	top keyword or any CSS selector
`data-id`	This attribute is used for deep linking.	any text value that may contain letters, digits, underscores or dashes
`data-regex`	This optional data attribute defines characters that should be ignored during the filtering. For example, data-regex="[^a-zA-Z0-9]+" ignores all characters except English letters and numbers.	JavaScript regex
`data-or`	Defines a group of controls that should be filtered though the "OR" logic	any text value, for example data-or="bags"
`data-mode`	Defines text filter mode: contains - find all elements that contain user input startsWith - find all elements that start with user input endsWith - find all elements that end with user input equal - find all elements that equal to user input	contains (default), startsWith, endsWith, equal