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

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