> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# panel
> Wraps other widgets in a panel for a consistent layout.
```ts Signature theme={"system"}
panel({
// Optional parameters
hidden?: function,
collapsed?: function,
templates?: object,
cssClasses?: object,
});
```
## Import
```js Package manager theme={"system"}
import { panel } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { panel } = instantsearch.widgets;
// or directly use instantsearch.widgets.panel()
```
Preview this widget and its behavior.
## 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`](/doc/api-reference/widgets/refinement-list/js)
becomes empty because of the current search results.
## Examples
```js JavaScript icon=code theme={"system"}
const refinementListWithPanel = panel({
templates: {
header: "Brand",
},
})(refinementList);
refinementListWithPanel({
container: "#refinement-list",
attribute: "brand",
});
```
## Options
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.
```js JavaScript icon=code theme={"system"}
panel({
hidden(options) {
return options.results.nbHits === 0;
},
});
```
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.
```js JavaScript icon=code theme={"system"}
panel({
collapsed: ({ state }) => {
return state.query.length === 0;
},
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
panel({
// ...
templates: {
// ...
},
});
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):
* `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.
```js JavaScript icon=code theme={"system"}
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates). 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](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#templating-your-ui) for more information.
The `html` function is available starting from v4.46.0.
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.
```js function theme={"system"}
panel({
// ...
templates: {
header(options, { html }) {
if (options.results) {
return html`Brand (${options.results.nbHits} results)`;
}
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
panel({
// ...
templates: {
header: "Brand ({{ results.nbHits }} results)",
},
});
```
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.
```js function theme={"system"}
panel({
// ...
templates: {
footer(options, { html }) {
if (options.results) {
return html`Brand (${options.results.nbHits} results)`;
}
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
panel({
// ...
templates: {
footer: "Brand ({{ results.nbHits }} results)",
},
});
```
The template used for displaying the collapse button. It exposes:
* `collapsed: boolean`. Whether the panel is currently collapsed.
```js function theme={"system"}
panel({
// ...
templates: {
collapseButtonText(options, { html }) {
return html`${options.collapsed ? "+" : "-"}`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
panel({
// ...
templates: {
collapseButtonText:
"{{#collapsed}}+{{/collapsed}}{{^collapsed}}-{{/collapsed}}",
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```