UI libraries / InstantSearch.js / Widgets

panel

Signature 
panel({
  // Optional parameters
  hidden: function,
  collapsed: function,
  templates: object,
  cssClasses: object,
});
Import
Copy 
1

import { panel } from 'instantsearch.js/es/widgets';
See code examples
See live example

About this widget

The panel widget wraps other widgets in a consistent panel design. It also reacts by adding a CSS class when the widget can no longer refine. For example, when a refinementList becomes empty because of the current search results.

Examples

Copy 
1
2
3
4
5
6
7
8
9
10

const refinementListWithPanel = panel({
  templates: {
    header: 'Brand',
  },
})(refinementList);

refinementListWithPanel({
  container: '#refinement-list',
  attribute: 'brand',
});

Options

Parameter Description
hidden
type: function
default: () => false
Optional

A function that is called on each render to determine if the panel should be hidden based on the render options. If the function returns true, the CSS class noRefinementRoot is applied and the wrapper is hidden.

This function receives all rendering parameters provided by the inner widget.
Copy 
1
2
3
4
5

panel({
  hidden(options) {
    return options.results.nbHits === 0;
  },
});
collapsed
type: function
Optional

A function that is called on each render to determine if the panel should be collapsed based on the render options. Providing this option adds the CSS class collapsibleRoot. If the function returns true, the CSS class collapsedRoot is applied.

This function receives all rendering parameters provided by the inner widget.
Copy 
1
2
3
4
5

panel({
  collapsed: ({ state }) => {
    return state.query.length === 0;
  },
});
templates
type: object
Optional

The templates to use for the widget.
Copy 
1
2
3
4
5
6

panel({
  // ...
  templates: {
    // ...
  },
});
cssClasses
type: object
default: {}
Optional

The CSS classes you can override:

  • root: the root element of the widget.
  • noRefinementRoot: the root element when there are no refinements.
  • collapsibleRoot: the root element when the panel is collapsible (collapsed is defined).
  • collapsedRoot: the root element if the panel is collapsed.
  • collapseButton: the panel collapse button element.
  • collapseIcon: the panel collapse icon element.
  • header: the panel header element.
  • body: the panel content element.
  • footer: the panel footer element.
Copy 
1
2
3
4
5
6
7
8
9
10

panel({
  // ...
  cssClasses: {
    root: 'MyCustomPanel',
    header: [
      'MyCustomPanelHeader',
      'MyCustomPanelHeader--subclass',
    ],
  },
});

Templates

You can customize parts of the widget’s UI using the Templates API.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.

The html function is available starting from v4.46.0.

Parameter Description
header
type: string|function
Optional

The template used for displaying the header. It exposes:

  • results: object: the complete response from the Algolia API. It contains the hits but also metadata about the page, number of hits, etc.
  • state: object: the complete state of the search.
  • searchMetadata: object: some metadata about the search. Currently, it only contains the attribute isSearchStalled.
  • helper: object: the instance of the helper.
  • createURL: function: the function to generate a URL from the search state.
  • ...: all rendering parameters provided by the inner widget.
Copy 
1
2
3
4
5
6
7
8
9
10

panel({
  // ...
  templates: {
    header(options, { html }) {
      if (options.results) {
        return html`<span>Brand (${options.results.nbHits} results)</span>`;
      }
    },
  },
});
type: string|function
Optional

The template used for displaying the footer. It exposes:

  • results: object: the complete response from the Algolia API. It contains the hits but also metadata about the page, number of hits, etc.
  • state: object: the complete state of the search.
  • searchMetadata: object: some metadata about the search. Currently, it only contains the attribute isSearchStalled.
  • helper: object: the instance of the helper.
  • createURL: function: the function to generate a URL from the search state.
  • ...: all rendering parameters provided by the inner widget.
Copy 
1
2
3
4
5
6
7
8
9
10

panel({
  // ...
  templates: {
    footer(options, { html }) {
      if (options.results) {
        return html`<span>Brand (${options.results.nbHits} results)</span>`;
      }
    },
  },
});
collapseButtonText
type: string|function
Optional

The template used for displaying the collapse button. It exposes:

  • collapsed: boolean: whether the panel is currently collapsed.
Copy 
1
2
3
4
5
6
7
8

panel({
  // ...
  templates: {
    collapseButtonText(options, { html }) {
      return html`<span>${options.collapsed ? '+' : '-'}</span>`;
    },
  },
});

HTML output

Copy 
1
2
3
4
5
6
7

<div class="ais-Panel">
  <div class="ais-Panel-header">
    <span>Header</span>
  </div>
  <div class="ais-Panel-body">Panel content</div>
  <div class="ais-Panel-footer">Footer</div>
</div>
Did you find this page helpful?
InstantSearch.js v4