Skip to main content
Signature
panel({
  // Optional parameters
  hidden?: function,
  collapsed?: function,
  templates?: object,
  cssClasses?: object,
});

​
Import

import { panel } from "instantsearch.js/es/widgets";
View demo

​
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

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

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

​
Options

​
hidden
function
default: () => false
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.
JavaScript
panel({
  hidden(options) {
    return options.results.nbHits === 0;
  },
});
​
collapsed
function
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.
JavaScript
panel({
  collapsed: ({ state }) => {
    return state.query.length === 0;
  },
});
​
templates
object
The templates to use for the widget.
JavaScript
panel({
  // ...
  templates: {
    // ...
  },
});
​
cssClasses
object
default:"{}"
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.
JavaScript
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.
​
header
string | function
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.
panel({
  // ...
  templates: {
    header(options, { html }) {
      if (options.results) {
        return html`<span>Brand (${options.results.nbHits} results)</span>`;
      }
    },
  },
});
​
footer
string | function
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.
panel({
  // ...
  templates: {
    footer(options, { html }) {
      if (options.results) {
        return html`<span>Brand (${options.results.nbHits} results)</span>`;
      }
    },
  },
});
​
collapseButtonText
string | function
The template used for displaying the collapse button. It exposes:
  • collapsed: boolean. Whether the panel is currently collapsed.
panel({
  // ...
  templates: {
    collapseButtonText(options, { html }) {
      return html`<span>${options.collapsed ? "+" : "-"}</span>`;
    },
  },
});

​
HTML output

HTML
<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>