API Reference / InstantSearch.js Widgets / panel
Apr. 24, 2019

panel

Widget signature 
instantsearch.widgets.panel({
  // Optional parameters
  hidden: function,
  collapsed: function,
  templates: object,
  cssClasses: object,
});
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 = instantsearch.widgets.panel({
  templates: {
    header: 'Brand',
  },
})(instantsearch.widgets.refinementList);

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

Options

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.
Copy 
1
2
3
4
5

instantsearch.widgets.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.
Copy 
1
2
3
4
5

instantsearch.widgets.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

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

The CSS classes to 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

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

Templates

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.
Copy 
1
2
3
4
5
6

instantsearch.widgets.panel({
  // ...
  templates: {
    header: 'Brand ({{ results.nbHits }} results)',
  },
});
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.
Copy 
1
2
3
4
5
6

instantsearch.widgets.panel({
  // ...
  templates: {
    footer: 'Brand ({{ results.nbHits }} results)',
  },
});
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

instantsearch.widgets.panel({
  // ...
  templates: {
    collapseButtonText:
      '{{#collapsed}}+{{/collapsed}}{{^collapsed}}-{{/collapsed}}',
  },
});

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 v3