panel

Signature

panel({
  // Optional parameters
  hidden?: function,
  collapsed?: function,
  templates?: object,
  cssClasses?: object,
});

Import

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

const { panel } = instantsearch.widgets;
// or directly use instantsearch.widgets.panel()

See this widget in action

Preview this widget and its behavior.

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

function

default: () => false

A function that runs on each render and decides, based on the render options, whether to hide the panel. If the function returns true, the panel adds the CSS class noRefinementRoot and hides the wrapper.This function receives all rendering parameters provided by the inner widget.

JavaScript

panel({
  hidden(options) {
    return options.results.nbHits === 0;
  },
});

function

A function that runs on each render and decides, based on the render options, whether to collapse the panel. Providing this option adds the CSS class collapsibleRoot. If the function returns true, the panel adds the CSS class collapsedRoot.This function receives all rendering parameters provided by the inner widget.

JavaScript

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

object

The templates to use for the widget.

JavaScript

panel({
  // ...
  templates: {
    // ...
  },
});

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 you set collapsed, which makes the panel collapsible.
collapsedRoot. The root element of a collapsed panel.
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 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.

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. 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>`;
      }
    },
  },
});

// String-based templates are deprecated, use functions instead.
panel({
  // ...
  templates: {
    header: "Brand ({{ results.nbHits }} results)",
  },
});

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. 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>`;
      }
    },
  },
});

// String-based templates are deprecated, use functions instead.
panel({
  // ...
  templates: {
    footer: "Brand ({{ results.nbHits }} results)",
  },
});

string | function

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

collapsed: boolean. true if the panel shows only its header, false if it shows its body.

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

// String-based templates are deprecated, use functions instead.
panel({
  // ...
  templates: {
    collapseButtonText:
      "{{#collapsed}}+{{/collapsed}}{{^collapsed}}-{{/collapsed}}",
  },
});

string | function

The text template used for the collapse button’s accessible name, set as its aria-label attribute. It must return plain text, not HTML. It exposes:

collapsed: boolean. true if the panel shows only its header, false if it shows its body.

If you don’t set collapseButtonText, the label defaults to “Expand panel” for a collapsed panel and “Collapse panel” when it’s expanded. If you set collapseButtonText without collapseButtonLabel, the button doesn’t get an aria-label, and its accessible name comes from your custom button content.

panel({
  // ...
  templates: {
    collapseButtonLabel({ collapsed }) {
      return collapsed ? "Show brands" : "Hide brands";
    },
  },
});

// String-based templates are deprecated, use functions instead.
panel({
  // ...
  templates: {
    collapseButtonLabel:
      "{{#collapsed}}Show brands{{/collapsed}}{{^collapsed}}Hide brands{{/collapsed}}",
  },
});

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>

InstantSearch.js

Import

See this widget in action

About this widget

Examples

Options

Templates

HTML output

​Import

See this widget in action

​About this widget

​Examples

​Options

​Templates

​HTML output

Import

About this widget

Examples

Options

Templates

HTML output