### Filterizr Installation

Source: https://context7.com/giotiskl/filterizr/llms.txt

Install Filterizr using npm or yarn. Import the library for use in CommonJS or ES modules. For jQuery integration, install the plugin and use the provided method.

```bash
npm install filterizr
# or
yarn add filterizr
```

```javascript
// CommonJS / ES module import (vanilla JS)
import Filterizr from 'filterizr';
```

```javascript
// jQuery plugin (via npm)
import $ from 'jquery';
import Filterizr from 'filterizr';
Filterizr.installAsJQueryPlugin($);
```

```html
<!-- CDN / script tag (vanilla JS global) -->
<script src="vanilla.filterizr.min.js"></script>
<script>
  new Filterizr('.filtr-container');
</script>
```

```html
<!-- CDN / script tag (jQuery plugin) -->
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="jquery.filterizr.min.js"></script>
<script>
  $('.filtr-container').filterizr();
</script>
```

--------------------------------

### Install Filterizr via npm

Source: https://github.com/giotiskl/filterizr/blob/master/README.md

Use npm to add Filterizr to your project dependencies.

```bash
npm install filterizr
```

--------------------------------

### Install Filterizr via yarn

Source: https://github.com/giotiskl/filterizr/blob/master/README.md

Use yarn to add Filterizr to your project dependencies.

```bash
yarn add filterizr
```

--------------------------------

### Install Filterizr as jQuery Plugin

Source: https://github.com/giotiskl/filterizr/blob/master/README.md

Extend jQuery with Filterizr functionality by calling a static method. Ensure jQuery is imported first.

```javascript
import $ from 'jquery';
import Filterizr from 'filterizr';

// This will extend the $.fn prototype with Filterizr
Filterizr.installAsJQueryPlugin($);

$('.filter-container').filterizr('filter', 5); // or any other Filterizr API call
```

--------------------------------

### Install Filterizr as jQuery Plugin

Source: https://context7.com/giotiskl/filterizr/llms.txt

Extends jQuery with a `.filterizr()` method for a jQuery-style API. Must be called once with the jQuery object before using jQuery-style calls.

```javascript
import $ from 'jquery';
import Filterizr from 'filterizr';

// Register the plugin
Filterizr.installAsJQueryPlugin($);

// Instantiate via jQuery (pass options object or omit for defaults)
$('.filtr-container').filterizr({
  gutterPixels: 10,
  animationDuration: 0.5,
  controlsSelector: '.fltr-controls',
});

// Call API methods via jQuery interface
$('.filtr-container').filterizr('filter', 'nature');
$('.filtr-container').filterizr('sort', 'sort', 'asc');
$('.filtr-container').filterizr('search', 'lake');
$('.filtr-container').filterizr('shuffle');
$('.filtr-container').filterizr('toggleFilter', 'city');
$('.filtr-container').filterizr('setOptions', { layout: 'packed' });

// Insert / remove items
const newNode = $('<div class="filtr-item" data-category="nature">…</div>').get(0);
$('.filtr-container').append(newNode);
$('.filtr-container').filterizr('insertItem', newNode);

$('.filtr-container').filterizr('removeItem', newNode);

// Destroy instance (also removes internal _fltr reference from the jQuery object)
$('.filtr-container').filterizr('destroy');
```

--------------------------------

### Sort by Custom Data Attribute

Source: https://github.com/giotiskl/filterizr/blob/master/CHANGELOG.md

Sort items based on custom data-attributes by calling `.filterizr('sort', 'attributeName', 'order')`. Remember to omit the 'data-' prefix from the attribute name. Example shown is for version 1.0.1.

```javascript
$('.filtr-container').filterizr('sort', 'mySortData', 'asc');
```

--------------------------------

### Initialize Filterizr with Different Layouts

Source: https://github.com/giotiskl/filterizr/blob/master/demo/index.html

Demonstrates initializing Filterizr with various layout options such as 'sameWidth', 'sameHeight', 'packed', 'horizontal', and 'vertical'. Each snippet configures a specific layout and gutter size for different visual arrangements.

```javascript
new window.Filterizr('.color-container-1', {
  controlsSelector: '.color-controls-1',
  gutterPixels: 10,
});
```

```javascript
new window.Filterizr('.color-container-2', {
  controlsSelector: '.color-controls-2',
  layout: 'sameWidth',
  gutterPixels: 10,
});
```

```javascript
new window.Filterizr('.color-container-3', {
  controlsSelector: '.color-controls-3',
  layout: 'sameHeight',
  gutterPixels: 10,
});
```

```javascript
new window.Filterizr('.color-container-4', {
  controlsSelector: '.color-controls-4',
  layout: 'packed',
  gutterPixels: 10,
});
```

```javascript
new window.Filterizr('.color-container-5', {
  controlsSelector: '.color-controls-5',
  layout: 'horizontal',
  gutterPixels: 10,
});
```

```javascript
new window.Filterizr('.color-container-6', {
  controlsSelector: '.color-controls-6',
  layout: 'vertical',
  gutterPixels: 10,
});
```

--------------------------------

### Filterizr.installAsJQueryPlugin($)

Source: https://context7.com/giotiskl/filterizr/llms.txt

Registers Filterizr as a jQuery plugin, extending $.fn with a .filterizr() method for jQuery-style API calls.

```APIDOC
## Filterizr.installAsJQueryPlugin($)

### Description
Static method that extends `$.fn` with a `.filterizr()` method, enabling the full jQuery plugin API. Must be called once with the jQuery object before any jQuery-style Filterizr calls.

### Parameters
#### Path Parameters
- **$** (jQuery Object) - Required - The jQuery object to extend.

### Request Example
```js
import $ from 'jquery';
import Filterizr from 'filterizr';

// Register the plugin
Filterizr.installAsJQueryPlugin($);

// Instantiate via jQuery
$('.filtr-container').filterizr({
  gutterPixels: 10,
  animationDuration: 0.5,
  controlsSelector: '.fltr-controls',
});

// Call API methods via jQuery interface
$('.filtr-container').filterizr('filter', 'nature');
$('.filtr-container').filterizr('removeItem', newNode);
$('.filtr-container').filterizr('destroy');
```

### Response
This method does not return a value.
```

--------------------------------

### Constructor — new Filterizr(selectorOrNode, options)

Source: https://context7.com/giotiskl/filterizr/llms.txt

Instantiates a Filterizr grid on a container element. It accepts a CSS selector or an HTMLElement and an optional options object to customize behavior and appearance. The constructor initializes event listeners, optionally mounts a loading spinner, waits for images to load, renders the initial layout, and fires the onInit callback.

```APIDOC
## Constructor — `new Filterizr(selectorOrNode, options)`

### Description
Instantiates a Filterizr grid on a container element. The first argument is a CSS selector string or a direct `HTMLElement` reference pointing to the `.filtr-container` wrapper. The second argument is an optional options object that overrides the defaults. On construction, Filterizr sets up window resize listeners, optionally mounts a built-in loading spinner, waits for all images to load, renders the initial layout, then fires the `onInit` callback.

### Parameters
#### Path Parameters
- **selectorOrNode** (string | HTMLElement) - Required - A CSS selector string or a direct `HTMLElement` reference pointing to the `.filtr-container` wrapper.
- **options** (object) - Optional - An object that overrides the default configuration options.

### Options
- **animationDuration** (number) - Default: `0.4` - Duration in seconds for CSS transitions.
- **delay** (number) - Default: `50` - Milliseconds delay between items for progressive/alternate animations.
- **delayMode** (string) - Default: `'progressive'` - Animation delay mode: `'progressive'` or `'alternate'`.
- **easing** (string) - Default: `'ease-in-out'` - CSS transition-timing-function for animations.
- **filter** (string) - Default: `'all'` - The initial active filter category.
- **layout** (string) - Default: `'sameSize'` - The layout mode: `'sameSize'`, `'sameHeight'`, `'sameWidth'`, `'packed'`, `'horizontal'`, `'vertical'`.
- **gutterPixels** (number) - Default: `10` - The gap in pixels between grid items.
- **multifilterLogicalOperator** (string) - Default: `'or'` - Logical operator for multifilter: `'or'` or `'and'`.
- **gridItemsSelector** (string) - Default: `'.filtr-item'` - Selector for grid items within the container.
- **controlsSelector** (string) - Default: `'.fltr-controls'` - Selector for control elements.
- **setupControls** (boolean) - Default: `true` - Whether to automatically set up controls.
- **filterOutCss** (object) - Default: `{ opacity: 0, transform: 'scale(0.5)' }` - CSS properties applied to items filtered out.
- **filterInCss** (object) - Default: `{ opacity: 1, transform: 'scale(1)' }` - CSS properties applied to items filtered in.
- **spinner** (object) - Configuration for the loading spinner.
  - **enabled** (boolean) - Default: `true` - Whether the spinner is enabled.
  - **fillColor** (string) - Default: `'#2184D0'` - The fill color of the spinner.
  - **styles** (object) - Custom CSS styles for the spinner.
- **callbacks** (object) - Callback functions to be executed at different stages.
  - **onInit** (function) - Called when the grid is initialized.
  - **onFilteringStart** (function) - Called when filtering begins.
  - **onFilteringEnd** (function) - Called when filtering ends.
  - **onShufflingStart** (function) - Called when shuffling begins.
  - **onShufflingEnd** (function) - Called when shuffling ends.
  - **onSortingStart** (function) - Called when sorting begins.
  - **onSortingEnd** (function) - Called when sorting ends.

### Request Example
```javascript
import Filterizr from 'filterizr';

// Minimal instantiation — uses all defaults
const filterizr = new Filterizr('.filtr-container');

// Full options instantiation
const filterizr = new Filterizr('.filtr-container', {
  animationDuration: 0.4,
  delay: 50,
  delayMode: 'progressive',
  easing: 'ease-in-out',
  filter: 'all',
  layout: 'sameSize',
  gutterPixels: 10,
  multifilterLogicalOperator: 'or',
  gridItemsSelector: '.filtr-item',
  controlsSelector: '.fltr-controls',
  setupControls: true,
  filterOutCss: { opacity: 0, transform: 'scale(0.5)' },
  filterInCss:  { opacity: 1, transform: 'scale(1)' },
  spinner: {
    enabled: true,
    fillColor: '#2184D0',
    styles: { height: '75px', width: '75px', margin: '0 auto', 'z-index': 2 },
  },
  callbacks: {
    onInit:          () => console.log('Grid initialized'),
    onFilteringStart: () => console.log('Filtering started'),
    onFilteringEnd:   () => console.log('Filtering complete'),
    onShufflingStart: () => console.log('Shuffling started'),
    onShufflingEnd:   () => console.log('Shuffling complete'),
    onSortingStart:   () => console.log('Sorting started'),
    onSortingEnd:     () => console.log('Sorting complete'),
  },
});
```
```

--------------------------------

### Initialize Filterizr with Controls

Source: https://github.com/giotiskl/filterizr/blob/master/demo/index.html

Initializes Filterizr with a container and specifies a selector for controls. Enables a spinner and sets gutter pixels. This is useful for setting up the main filtering interface.

```javascript
window.filterizr = new window.Filterizr('.filtr-container', {
  controlsSelector: '.fltr-controls',
  gutterPixels: 15,
  spinner: {
    enabled: true,
  },
});
```

--------------------------------

### Instantiate Filterizr with Options

Source: https://context7.com/giotiskl/filterizr/llms.txt

Instantiate Filterizr with default or custom options. The options object allows configuration of animation, layout, callbacks, and more. Ensure the selector matches your container element.

```javascript
import Filterizr from 'filterizr';

// Minimal instantiation — uses all defaults
const filterizr = new Filterizr('.filtr-container');

// Full options instantiation
const filterizr = new Filterizr('.filtr-container', {
  animationDuration: 0.4,       // seconds for CSS transition
  delay: 50,                    // ms delay between items (progressive/alternate)
  delayMode: 'progressive',     // 'progressive' | 'alternate'
  easing: 'ease-in-out',        // any valid CSS transition-timing-function
  filter: 'all',                // initial active filter
  layout: 'sameSize',           // 'sameSize'|'sameHeight'|'sameWidth'|'packed'|'horizontal'|'vertical'
  gutterPixels: 10,             // gap between grid items in px
  multifilterLogicalOperator: 'or',  // 'or' | 'and'
  gridItemsSelector: '.filtr-item',
  controlsSelector: '.fltr-controls',
  setupControls: true,
  filterOutCss: { opacity: 0, transform: 'scale(0.5)' },
  filterInCss:  { opacity: 1, transform: 'scale(1)' },
  spinner: {
    enabled: true,
    fillColor: '#2184D0',
    styles: { height: '75px', width: '75px', margin: '0 auto', 'z-index': 2 },
  },
  callbacks: {
    onInit:          () => console.log('Grid initialized'),
    onFilteringStart: () => console.log('Filtering started'),
    onFilteringEnd:   () => console.log('Filtering complete'),
    onShufflingStart: () => console.log('Shuffling started'),
    onShufflingEnd:   () => console.log('Shuffling complete'),
    onSortingStart:   () => console.log('Sorting started'),
    onSortingEnd:     () => console.log('Sorting complete'),
  },
});
```

--------------------------------

### Import Filterizr Vanilla JavaScript

Source: https://github.com/giotiskl/filterizr/blob/master/README.md

Import the default Filterizr export for use in projects managed with npm.

```javascript
import Filterizr from 'filterizr'
```

--------------------------------

### Declarative HTML Controls for Filterizr

Source: https://context7.com/giotiskl/filterizr/llms.txt

Uses `data-*` attributes on HTML elements to control filtering, sorting, and searching without JavaScript. Ensure `setupControls: true` is set (default) and `controlsSelector` is configured.

```html
<!-- Filter controls: data-filter targets category values or "all" -->
<ul class="controls">
  <li data-filter="all">All</li>
  <li data-filter="nature">Nature</li>
  <li data-filter="city">City</li>
</ul>

<!-- Multi-filter toggle controls: each click toggles the category in/out -->
<ul class="controls">
  <li data-multifilter="nature">Nature</li>
  <li data-multifilter="city">City</li>
</ul>

<!-- Shuffle, sort direction, sort attribute controls -->
<button data-shuffle>Shuffle</button>
<button data-sortAsc>A → Z</button>
<button data-sortDesc>Z → A</button>
<select data-sortOrder>
  <option value="index">Original order</option>
  <option value="sort">Alphabetical</option>
</select>

<!-- Search input: live search as the user types -->
<input type="text" data-search placeholder="Search…" />

<script>
  // Pass the common selector for all controls to one instance
  new Filterizr('.filtr-container', {
    controlsSelector: '[data-filter], [data-multifilter], [data-shuffle], [data-sortAsc], [data-sortDesc], [data-sortOrder], [data-search]',
  });
</script>
```

--------------------------------

### Declarative HTML Controls

Source: https://context7.com/giotiskl/filterizr/llms.txt

Filterizr automatically binds controls using data-* attributes when setupControls is true, allowing for interactive filtering, sorting, and searching without explicit JavaScript.

```APIDOC
## Declarative HTML Controls

### Description
Filterizr discovers and binds controls automatically when `setupControls: true` (the default). Control elements within `controlsSelector` (or anywhere on the page when `controlsSelector` is `''`) use `data-*` attributes to wire up interactions without any JavaScript.

### Supported Data Attributes
- **`data-filter`**: Targets category values or "all" for filtering.
- **`data-multifilter`**: Toggles the specified category in or out.
- **`data-shuffle`**: Triggers a shuffle of the grid items.
- **`data-sortAsc`**: Sorts items in ascending order.
- **`data-sortDesc`**: Sorts items in descending order.
- **`data-sortOrder`**: A select element to specify the sort attribute (e.g., `value="sort"`).
- **`data-search`**: An input field for live search functionality.

### Request Example
```html
<!-- Filter controls -->
<ul class="controls">
  <li data-filter="all">All</li>
  <li data-filter="nature">Nature</li>
</ul>

<!-- Search input -->
<input type="text" data-search placeholder="Search…" />

<script>
  // Instantiate Filterizr with controls selector
  new Filterizr('.filtr-container', {
    controlsSelector: '[data-filter], [data-multifilter], [data-shuffle], [data-sortAsc], [data-sortDesc], [data-sortOrder], [data-search]',
  });
</script>
```
```

--------------------------------

### Update Options at Runtime with filterizr.setOptions()

Source: https://context7.com/giotiskl/filterizr/llms.txt

Merges a partial options object into the current configuration without re-instantiating the grid. Handles event rebinding, transition updates, and re-rendering when relevant options change.

```javascript
// Change layout at runtime
filterizr.setOptions({ layout: 'packed' });

// Update gutter and animation speed simultaneously
filterizr.setOptions({
  gutterPixels: 20,
  animationDuration: 0.3,
  easing: 'ease-in',
});

// Swap callbacks without losing existing ones
filterizr.setOptions({
  callbacks: {
    onFilteringEnd: () => updateResultCount(),
  },
});

// Programmatically update active filter and search term together
filterizr.setOptions({
  filter: 'nature',
  searchTerm: 'lake',
});
```

--------------------------------

### filterizr.setOptions(newOptions)

Source: https://context7.com/giotiskl/filterizr/llms.txt

Merges a partial options object into the current configuration without re-instantiating the grid. Handles unbinding and rebinding of events when callbacks or animation properties change, updates transition styles when easing or timing changes, and re-renders when `gutterPixels` or `filter` changes.

```APIDOC
## `filterizr.setOptions(newOptions)` — Update options at runtime

Merges a partial options object into the current configuration without re-instantiating the grid. Handles unbinding and rebinding of events when callbacks or animation properties change, updates transition styles when easing or timing changes, and re-renders when `gutterPixels` or `filter` changes.

### Parameters
#### Path Parameters
- **newOptions** (object) - Required - An object containing the options to update.

### Request Example
```js
// Change layout at runtime
filterizr.setOptions({ layout: 'packed' });

// Update gutter and animation speed simultaneously
filterizr.setOptions({
  gutterPixels: 20,
  animationDuration: 0.3,
  easing: 'ease-in',
});

// Swap callbacks without losing existing ones
filterizr.setOptions({
  callbacks: {
    onFilteringEnd: () => updateResultCount(),
  },
});

// Programmatically update active filter and search term together
filterizr.setOptions({
  filter: 'nature',
  searchTerm: 'lake',
});
```
```

--------------------------------

### Apply Search Filter with API

Source: https://github.com/giotiskl/filterizr/blob/master/CHANGELOG.md

Use the `.filterizr('search', text)` method to apply a search filter to the gallery. This method is available from version 1.2.0 onwards.

```javascript
$('.filtr-container').filterizr('search', 'some text');
```

--------------------------------

### Add New Item with filterizr.insertItem()

Source: https://context7.com/giotiskl/filterizr/llms.txt

Asynchronously appends a new DOM node to the filter container, waits for images to load, and re-renders the grid. The node must have appropriate `data-category` and `data-sort` attributes.

```javascript
// Create and insert a new grid item dynamically
const newItem = document.createElement('div');
newItem.classList.add('filtr-item');
newItem.setAttribute('data-category', 'nature');
newItem.setAttribute('data-sort', 'Misty Forest');
newItem.innerHTML = '<img src="forest.jpg" alt="Misty Forest" /><span>Misty Forest</span>';

// Append to DOM first, then register with Filterizr
document.querySelector('.filtr-container').appendChild(newItem);
filterizr.insertItem(newItem).then(() => {
  console.log('Item inserted and grid re-rendered');
});
```

--------------------------------

### filterizr.insertItem(node)

Source: https://context7.com/giotiskl/filterizr/llms.txt

Asynchronously appends a new DOM node into the filter container, waits for any images inside it to finish loading, then re-renders the grid to accommodate the new item. The node must have the appropriate `data-category` (and optional `data-sort`) attributes.

```APIDOC
## `filterizr.insertItem(node)` — Add a new item to the grid

Asynchronously appends a new DOM node into the filter container, waits for any images inside it to finish loading, then re-renders the grid to accommodate the new item. The node must have the appropriate `data-category` (and optional `data-sort`) attributes.

### Parameters
#### Path Parameters
- **node** (HTMLElement) - Required - The DOM node to insert into the grid.

### Request Example
```js
// Create and insert a new grid item dynamically
const newItem = document.createElement('div');
newItem.classList.add('filtr-item');
newItem.setAttribute('data-category', 'nature');
newItem.setAttribute('data-sort', 'Misty Forest');
newItem.innerHTML = '<img src="forest.jpg" alt="Misty Forest" /><span>Misty Forest</span>';

// Append to DOM first, then register with Filterizr
document.querySelector('.filtr-container').appendChild(newItem);
filterizr.insertItem(newItem).then(() => {
  console.log('Item inserted and grid re-rendered');
});
```
```

--------------------------------

### Filterizr Layout Modes

Source: https://context7.com/giotiskl/filterizr/llms.txt

Configure the layout of filtered items using the 'layout' option. Supported modes include 'sameSize', 'sameHeight', 'sameWidth', 'packed', 'horizontal', and 'vertical'. You can also switch layouts at runtime using the setOptions method.

```javascript
new Filterizr('.gallery', { layout: 'sameSize', gutterPixels: 8 });
```

```javascript
new Filterizr('.gallery', { layout: 'sameHeight', gutterPixels: 8 });
```

```javascript
new Filterizr('.gallery', { layout: 'sameWidth', gutterPixels: 8 });
```

```javascript
new Filterizr('.gallery', { layout: 'packed', gutterPixels: 8 });
```

```javascript
new Filterizr('.gallery', { layout: 'horizontal', gutterPixels: 8 });
```

```javascript
new Filterizr('.gallery', { layout: 'vertical', gutterPixels: 8 });
```

```javascript
filterizr.setOptions({ layout: 'packed' });
```

--------------------------------

### Filter Grid Items by Category

Source: https://context7.com/giotiskl/filterizr/llms.txt

Use the `filter` method to show items matching specific categories. Pass 'all' to display all items. This method triggers filtering animations and callbacks.

```javascript
// Show all items
filterizr.filter('all');

// Filter to a single string category
filterizr.filter('nature');

// Filter to a numeric category (matches data-category="2")
filterizr.filter(2);

// Filter to multiple categories simultaneously (OR logic by default)
filterizr.filter(['nature', 'city']);

// Expected: items with data-category="nature" or data-category="city" animate in;
//           all others animate out with scale(0.5) + opacity 0
```

--------------------------------

### Randomly Shuffle Grid Items with filterizr.shuffle()

Source: https://context7.com/giotiskl/filterizr/llms.txt

Randomizes the positions of all currently visible grid items, ensuring at least one position change. Fires `onShufflingStart` and `onShufflingEnd` callbacks.

```javascript
// Shuffle currently visible items
filterizr.shuffle();

// Typical usage: hook to a button click
document.querySelector('#shuffle-btn').addEventListener('click', () => {
  filterizr.shuffle();
});
```

--------------------------------

### Toggle Filter with API

Source: https://github.com/giotiskl/filterizr/blob/master/CHANGELOG.md

Use the `.filterizr('toggleFilter', toggledFilter)` method for multi-filtering mode, allowing users to activate and deactivate filters. Available from version 1.1.0.

```javascript
$('.filtr-container').filterizr('toggleFilter', 'some filter');
```

--------------------------------

### Toggle Multi-Filter Mode with filterizr.toggleFilter()

Source: https://context7.com/giotiskl/filterizr/llms.txt

Toggles a category in or out of the active multi-filter set. Uses the `multifilterLogicalOperator` to determine visibility. Removing all filters resets the grid to show all items.

```javascript
filterizr.toggleFilter('nature');  // → shows 'nature' items
filterizr.toggleFilter('city');    // → shows 'nature' OR 'city' items (with 'or' operator)
filterizr.toggleFilter('nature');  // → removes 'nature', shows only 'city' items

// Switch to AND logic so only items belonging to BOTH categories are shown
filterizr.setOptions({ multifilterLogicalOperator: 'and' });
filterizr.toggleFilter('nature');  // → shows items that are BOTH 'city' AND 'nature'
```

--------------------------------

### Keyword Search with filterizr.search()

Source: https://context7.com/giotiskl/filterizr/llms.txt

Adds a search layer over the active filter. Items not containing the `searchTerm` (case-insensitive) are hidden. An empty string clears the search.

```html
<!-- Items must have visible text content for search to match against -->
<div class="filtr-item" data-category="nature">
  <img src="lake.jpg" />
  <span>Alpine Lake</span>
</div>
```

```javascript
// Search for items containing "lake"
filterizr.search('lake');
// → only items whose text includes "lake" (case-insensitive) remain visible

// Clear search
filterizr.search('');
// → reverts to current category filter, shows all matching items again

// Combine with a category filter: only 'nature' items AND matching "lake"
filterizr.filter('nature');
filterizr.search('lake');
```

--------------------------------

### filterizr.shuffle()

Source: https://context7.com/giotiskl/filterizr/llms.txt

Randomizes the positions of all currently visible grid items, guaranteeing at least one position change from the current arrangement. Fires `onShufflingStart` / `onShufflingEnd` callbacks.

```APIDOC
## `filterizr.shuffle()` — Randomly shuffle grid items

Randomizes the positions of all currently visible grid items, guaranteeing at least one position change from the current arrangement. Fires `onShufflingStart` / `onShufflingEnd` callbacks.

### Request Example
```js
// Shuffle currently visible items
filterizr.shuffle();

// Typical usage: hook to a button click
document.querySelector('#shuffle-btn').addEventListener('click', () => {
  filterizr.shuffle();
});
```
```

--------------------------------

### Handle Sort and Shuffle Button Clicks

Source: https://github.com/giotiskl/filterizr/blob/master/demo/index.html

Adds click event listeners to sort and shuffle buttons. It manages the 'active' class for sort controls and removes 'active' class from all sort controls when the shuffle button is clicked.

```javascript
const sortControls = document.querySelectorAll('.sort-btn');
Array.from(sortControls).forEach((node) => node.addEventListener('click', function() {
  sortControls.forEach((control) => control.classList.remove('active'));
  node.classList.add('active');
}));

const shuffleControl = document.querySelector('.shuffle-btn');
shuffleControl.addEventListener('click', function() {
  sortControls.forEach((control) => control.classList.remove('active'));
});
```

--------------------------------

### filterizr.search(searchTerm)

Source: https://context7.com/giotiskl/filterizr/llms.txt

Adds a search layer on top of the active filter. Items whose text content does not contain the `searchTerm` (case-insensitive) are filtered out. Passing an empty string clears the search and reverts to the current category filter.

```APIDOC
## `filterizr.search(searchTerm)` — Keyword search over grid items

Adds a search layer on top of the active filter. Items whose text content does not contain the `searchTerm` (case-insensitive) are filtered out. Passing an empty string clears the search and reverts to the current category filter.

### Parameters
#### Path Parameters
- **searchTerm** (string) - Required - The text to search for within item content. An empty string clears the search.

### Request Example
```js
// Search for items containing "lake"
filterizr.search('lake');
// → only items whose text includes "lake" (case-insensitive) remain visible

// Clear search
filterizr.search('');
// → reverts to current category filter, shows all matching items again

// Combine with a category filter: only 'nature' items AND matching "lake"
filterizr.filter('nature');
filterizr.search('lake');
```
```

--------------------------------

### filterizr.filter(category)

Source: https://context7.com/giotiskl/filterizr/llms.txt

Filters the grid items to show only those matching the specified category. Accepts a string, number, or an array of values. Passing 'all' displays all items. This method triggers filtering callbacks and applies CSS transitions for items entering and exiting the view.

```APIDOC
## `filterizr.filter(category)`

### Description
Shows only the grid items whose `data-category` attribute matches the given category string, number, or array of values. Pass `'all'` to show every item. Triggers `onFilteringStart` and `onFilteringEnd` callbacks and applies `filterInCss`/`filterOutCss` transitions.

### Parameters
#### Path Parameters
- **category** (string | number | Array<string | number>) - Required - The category or categories to filter by. Use `'all'` to display all items.

### Request Example
```javascript
// Show all items
filterizr.filter('all');

// Filter to a single string category
filterizr.filter('nature');

// Filter to a numeric category (matches data-category="2")
filterizr.filter(2);

// Filter to multiple categories simultaneously (OR logic by default)
filterizr.filter(['nature', 'city']);
```

### Response
#### Success Response (void)
This method does not return a value, but it modifies the grid's visible items and triggers callbacks.

#### Response Example
// No response body, modifies the DOM and triggers callbacks.
// Expected: items with data-category="nature" or data-category="city" animate in;
//           all others animate out with scale(0.5) + opacity 0
```

--------------------------------

### Handle Simple Filter Clicks

Source: https://github.com/giotiskl/filterizr/blob/master/demo/index.html

Adds click event listeners to list items for simple filtering. It removes the 'active' class from all filters and adds it to the clicked item, ensuring only one filter is active at a time.

```javascript
const simpleFilters = document.querySelectorAll('.simplefilter li');
Array.from(simpleFilters).forEach((node) => node.addEventListener('click', function() {
  simpleFilters.forEach((filter) => filter.classList.remove('active'));
  node.classList.add('active');
}));
```

--------------------------------

### HTML Structure for Filterizr

Source: https://context7.com/giotiskl/filterizr/llms.txt

This is the basic HTML structure required for Filterizr to function. Items are defined within a container and each item needs a `data-category` and `data-sort` attribute.

```html
<!-- HTML structure required by Filterizr -->
<div class="filtr-container">
  <div class="filtr-item" data-category="nature"    data-sort="Alpine Lake">
    <img src="lake.jpg" alt="Alpine Lake" />
  </div>
  <div class="filtr-item" data-category="city"      data-sort="Night Skyline">
    <img src="city.jpg" alt="Night Skyline" />
  </div>
  <div class="filtr-item" data-category="nature, city" data-sort="River Bridge">
    <img src="bridge.jpg" alt="River Bridge" />
  </div>
</div>
```

--------------------------------

### Sort Grid Items with filterizr.sort()

Source: https://context7.com/giotiskl/filterizr/llms.txt

Reorders visible grid items by a specified `data-*` attribute. Use 'index' to restore original DOM order. `sortOrder` can be 'asc' or 'desc'.

```html
<!-- Items carry a custom data-sort attribute -->
<div class="filtr-item" data-category="nature" data-sort="Alpine Lake"> … </div>
<div class="filtr-item" data-category="city"   data-sort="Night Skyline"> … </div>
```

```javascript
// Sort alphabetically ascending by data-sort value
filterizr.sort('sort', 'asc');

// Sort alphabetically descending
filterizr.sort('sort', 'desc');

// Restore original DOM insertion order
filterizr.sort('index', 'asc');

// Sort by a custom numeric attribute: data-year="2023"
filterizr.sort('year', 'desc');
```

--------------------------------

### Handle Multi-Filter Clicks

Source: https://github.com/giotiskl/filterizr/blob/master/demo/index.html

Adds click event listeners to list items for multifilter functionality. It toggles the 'active' class on the clicked item, allowing multiple filters to be selected simultaneously.

```javascript
const multiFilters = document.querySelectorAll('.multifilter li');
Array.from(multiFilters).forEach((node) => node.addEventListener('click', function() {
  node.classList.toggle('active');
}));
```

--------------------------------

### filterizr.sort(sortAttr, sortOrder)

Source: https://context7.com/giotiskl/filterizr/llms.txt

Reorders visible grid items by a `data-*` attribute. `sortAttr` corresponds to the suffix of the HTML data attribute (e.g., 'sort' maps to `data-sort`). Use 'index' to restore original DOM order. `sortOrder` is 'asc' (default) or 'desc'. Fires `onSortingStart` / `onSortingEnd` callbacks.

```APIDOC
## `filterizr.sort(sortAttr, sortOrder)` — Sort grid items

Reorders visible grid items by a `data-*` attribute. `sortAttr` corresponds to the suffix of the HTML data attribute (e.g., `'sort'` maps to `data-sort`). Use `'index'` to restore original DOM order. `sortOrder` is `'asc'` (default) or `'desc'`. Fires `onSortingStart` / `onSortingEnd` callbacks.

### Parameters
#### Path Parameters
- **sortAttr** (string) - Required - The attribute to sort by (e.g., 'sort' for `data-sort`, or 'index' for original order).
- **sortOrder** (string) - Optional - The order of sorting ('asc' or 'desc'). Defaults to 'asc'.

### Request Example
```js
// Sort alphabetically ascending by data-sort value
filterizr.sort('sort', 'asc');

// Sort alphabetically descending
filterizr.sort('sort', 'desc');

// Restore original DOM insertion order
filterizr.sort('index', 'asc');

// Sort by a custom numeric attribute: data-year="2023"
filterizr.sort('year', 'desc');
```
```

--------------------------------

### destroy()

Source: https://context7.com/giotiskl/filterizr/llms.txt

Tears down the Filterizr instance by removing event listeners, detaching injected styles, and cleaning up internal state.

```APIDOC
## destroy()

### Description
Removes all event listeners (window resize, control click handlers), detaches Filterizr's injected styles from the DOM, and cleans up the internal state. Should be called before removing the container element or navigating away in a single-page application.

### Method
`destroy()`

### Request Example
```js
// Destroy the instance and clean up
filterizr.destroy();

// SPA example: destroy before unmounting a component
function unmountGallery() {
  filterizr.destroy();
  document.querySelector('.filtr-container').remove();
}
```

### Response
This method does not return a value.
```

--------------------------------

### filterizr.toggleFilter(category)

Source: https://context7.com/giotiskl/filterizr/llms.txt

Toggles a single category in or out of the active multi-filter set without replacing the current filter. Uses `multifilterLogicalOperator` ('or' or 'and') to decide which items are visible. Calling toggle on an already-active filter removes it; if all filters are removed, the grid resets to 'all'.

```APIDOC
## `filterizr.toggleFilter(category)` — Toggle multi-filter mode

Toggles a single category in or out of the active multi-filter set without replacing the current filter. Uses `multifilterLogicalOperator` (`'or'` or `'and'`) to decide which items are visible. Calling toggle on an already-active filter removes it; if all filters are removed, the grid resets to `'all'`.

### Parameters
#### Path Parameters
- **category** (string) - Required - The category to toggle.

### Request Example
```js
// Start with no active filter (all items shown)
filterizr.toggleFilter('nature');  // → shows 'nature' items
filterizr.toggleFilter('city');    // → shows 'nature' OR 'city' items (with 'or' operator)
filterizr.toggleFilter('nature');  // → removes 'nature', shows only 'city' items

// Switch to AND logic so only items belonging to BOTH categories are shown
filterizr.setOptions({ multifilterLogicalOperator: 'and' });
filterizr.toggleFilter('nature');  // → shows items that are BOTH 'city' AND 'nature'
```
```

--------------------------------

### Destroy Filterizr Instance

Source: https://context7.com/giotiskl/filterizr/llms.txt

Cleans up Filterizr by removing event listeners, injected styles, and internal state. Call this before removing the container or navigating away in SPAs.

```javascript
filterizr.destroy();
```

```javascript
function unmountGallery() {
  filterizr.destroy();
  document.querySelector('.filtr-container').remove();
}
```

--------------------------------

### removeItem(node)

Source: https://context7.com/giotiskl/filterizr/llms.txt

Removes an existing DOM node from the filter container and re-renders the grid. The node must be a child of the '.filtr-container'.

```APIDOC
## removeItem(node)

### Description
Removes an existing DOM node from the filter container and immediately re-renders the remaining items to close the gap. The node must already be a child of the `.filtr-container`.

### Parameters
#### Path Parameters
- **node** (DOM Node) - Required - The DOM node to remove from the grid.

### Request Example
```js
// Remove a specific item by reference
const itemToRemove = document.querySelector('.filtr-item[data-sort="Alpine Lake"]');
filterizr.removeItem(itemToRemove);
```

### Response
This method does not return a value, but modifies the DOM in place.
```

--------------------------------

### Remove Item from Filterizr Grid

Source: https://context7.com/giotiskl/filterizr/llms.txt

Removes a DOM node from the filter container and re-renders the grid. Ensure the node is a child of the `.filtr-item`.

```javascript
const itemToRemove = document.querySelector('.filtr-item[data-sort="Alpine Lake"]');
filterizr.removeItem(itemToRemove);
```

```javascript
document.querySelectorAll('.filtr-item .delete-btn').forEach(btn => {
  btn.addEventListener('click', (e) => {
    const item = e.target.closest('.filtr-item');
    filterizr.removeItem(item);
  });
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.