# Collapse Component

Collapse panels are used to group and hide complex content areas, improving page organization.

The collapse component does not include default styles. You must either create your own styles or use it alongside other components.

## Usage {#usage}

Import the component:

```js
import 'mdui/components/collapse.js';
import 'mdui/components/collapse-item.js';
```

Import the TypeScript type:

```ts
import type { Collapse } from 'mdui/components/collapse.js';
import type { CollapseItem } from 'mdui/components/collapse-item.js';
```

Example:

```html
<mdui-collapse>
  <mdui-collapse-item header="first header">first content</mdui-collapse-item>
  <mdui-collapse-item header="second header">second content</mdui-collapse-item>
</mdui-collapse>
```

## Examples {#examples}

### Panel Header and Content {#example-header}

You can set the panel header text using the `header` attribute of the `<mdui-collapse-item>` component. Alternatively, use the `header` slot to specify the panel header element. The default slot of the component is for the panel content.

```html
<mdui-list>
  <mdui-collapse>
    <mdui-collapse-item>
      <mdui-list-item slot="header" icon="near_me">Item 1</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 1 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
    <mdui-collapse-item>
      <mdui-list-item slot="header" icon="near_me">Item 2</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 2 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
  </mdui-collapse>
</mdui-list>
```

### Accordion Mode {#example-accordion}

To enable accordion mode, add the `accordion` attribute to the `<mdui-collapse>` component. In this mode, only one panel can be open at a time.

```html
<mdui-list>
  <mdui-collapse accordion>
    <mdui-collapse-item>
      <mdui-list-item slot="header" icon="near_me">Item 1</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 1 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
    <mdui-collapse-item>
      <mdui-list-item slot="header" icon="near_me">Item 2</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 2 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
  </mdui-collapse>
</mdui-list>
```

### Setting the Active Panel {#example-value}

The `value` attribute of the `<mdui-collapse>` component can be used to get or set the currently open panel.

In accordion mode, `value` is a string and can be manipulated using either attribute or property. In non-accordion mode, `value` is an array and can only be manipulated using JavaScript property.

```html
<mdui-list>
  <mdui-list-subheader>Accordion Mode</mdui-list-subheader>
  <mdui-collapse accordion value="item-1">
    <mdui-collapse-item value="item-1">
      <mdui-list-item slot="header" icon="near_me">Item 1</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 1 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
    <mdui-collapse-item value="item-2">
      <mdui-list-item slot="header" icon="near_me">Item 2</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 2 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
  </mdui-collapse>

  <mdui-list-subheader>Non-Accordion Mode</mdui-list-subheader>
  <mdui-collapse class="example-value">
    <mdui-collapse-item value="item-1">
      <mdui-list-item slot="header" icon="near_me">Item 1</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 1 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
    <mdui-collapse-item value="item-2">
      <mdui-list-item slot="header" icon="near_me">Item 2</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 2 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
  </mdui-collapse>
</mdui-list>

<script>
  const collapse = document.querySelector(".example-value");
  collapse.value = ["item-1", "item-2"];
</script>
```

### Disabled State {#example-disabled}

To disable the entire collapse panel group, add the `disabled` attribute to the `<mdui-collapse>` component. To disable a specific collapse panel, add the `disabled` attribute to the `<mdui-collapse-item>`.

```html
<mdui-list>
  <mdui-list-subheader>All Disabled</mdui-list-subheader>
  <mdui-collapse disabled>
    <mdui-collapse-item>
      <mdui-list-item slot="header" icon="near_me">Item 1</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 1 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
    <mdui-collapse-item>
      <mdui-list-item slot="header" icon="near_me">Item 2</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 2 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
  </mdui-collapse>

  <mdui-list-subheader>Disable the First Panel</mdui-list-subheader>
  <mdui-collapse>
    <mdui-collapse-item disabled>
      <mdui-list-item slot="header" icon="near_me">Item 1</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 1 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
    <mdui-collapse-item>
      <mdui-list-item slot="header" icon="near_me">Item 2</mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 2 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
  </mdui-collapse>
</mdui-list>
```

### Triggering Element for Collapse {#example-trigger}

By default, clicking the entire panel header area triggers the collapse. You can specify a different trigger element using the `trigger` attribute of the `<mdui-collapse-item>` component. The `trigger` attribute can be a CSS selector or a DOM element.

```html
<mdui-list>
  <mdui-collapse>
    <mdui-collapse-item trigger=".example-trigger">
      <mdui-list-item slot="header" icon="near_me">
        Item 1
        <mdui-icon slot="end-icon" class="example-trigger" name="keyboard_arrow_down"></mdui-icon>
      </mdui-list-item>
      <div style="margin-left: 2.5rem">
        <mdui-list-item>Item 1 - subitem</mdui-list-item>
      </div>
    </mdui-collapse-item>
  </mdui-collapse>
</mdui-list>
```

## mdui-collapse-item API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Specifies the value of the collapsible panel item.</p>
</td>
  </tr>
  <tr>
    <td>header</td>
    <td>header</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Sets the header text for the collapsible panel item.</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Disables the collapsible panel item.</p>
</td>
  </tr>
  <tr>
    <td>trigger</td>
    <td>trigger</td>
    <td>false</td>
    <td>string | HTMLElement | JQ&lt;HTMLElement&gt;</td>
    <td></td>
    <td><p>The element that toggles collapse on click. This can be a CSS selector, a DOM element, or a <a href="/en/docs/2/functions/jq">JQ object</a>. By default, the entire header area is the trigger.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>open</td>
    <td><p>Emitted when the collapse item starts to open.</p>
</td>
  </tr>
  <tr>
    <td>opened</td>
    <td><p>Emitted after the collapse item has opened and the animations are completed.</p>
</td>
  </tr>
  <tr>
    <td>close</td>
    <td><p>Emitted when the collapse item starts to close.</p>
</td>
  </tr>
  <tr>
    <td>closed</td>
    <td><p>Emitted after the collapse item has closed and the animations are completed.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Main content of the collapsible panel item.</p>
</td>
  </tr>
  <tr>
    <td>header</td>
    <td><p>Content of the collapsible panel item&#39;s header.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>header</td>
    <td><p>Content of the collapsible panel&#39;s header.</p>
</td>
  </tr>
  <tr>
    <td>body</td>
    <td><p>Content of the collapsible panel&#39;s body.</p>
</td>
  </tr>
</tbody>
</table>

## mdui-collapse API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>accordion</td>
    <td>accordion</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Activates accordion mode.</p>
</td>
  </tr>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>false</td>
    <td>string | string[]</td>
    <td></td>
    <td><p>Specifies the open <code>&lt;mdui-collapse-item&gt;</code> value.</p>
<p><strong>Note</strong>: The HTML attribute is always a string and can only be set initially when <code>accordion</code> is <code>true</code>. The JavaScript property is a string when <code>accordion</code> is <code>true</code> and a string array when <code>accordion</code> is <code>false</code>. To change this value when <code>accordion</code> is <code>false</code>, update the JavaScript property.</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Disables the collapsible panel.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>change</td>
    <td><p>Emitted when the currently open collapsible item changes.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>The <code>&lt;mdui-collapse-item&gt;</code> components.</p>
</td>
  </tr>
</tbody>
</table>