# Accordion

## When to use this component

Use the Accordion component to:

- allow users to focus on one section at a time
- group related filters or form controls in a compact space

## When not to use this component

Do not use the accordion component for:

- content that users need to see all at once
- short content that does not need to be hidden
- critical information that must be visible by default

## How it works

### Installation

To install the components, [go to the get started guide for developers](https://github.com/springernature/elements).

To use the Accordion component, enter the following command in your Terminal:

```bash
npm install @springernature/elements
```

### Styles

Import the styles of the Accordion component into your `scss` file:

```scss
@import '../path/to/@springernature/elements/components/eds-c-accordion';
```

### Variants

We provide templates for 2 different use cases.

#### Mobile navigation

Use the basic `eds-c-accordion` template for mobile navigation menus. This variant includes the colored strip indicator and specialized layout for navigation items.

| Name                 | Description                                                                        | Required |
|----------------------|------------------------------------------------------------------------------------|:--------:|
| id                   | Unique identifier for the accordion instance.                                      |    ✅    |
| title                | The title text displayed in the accordion header.                                  |    ✅    |
| iconURL              | URL of the SVG icon used for expand/collapse indicator.                            |    ✅    |
| headingLevel         | The heading level (1-6) for the accordion title.                                   |    ✅    |
| content              | HTML content to display when the accordion is expanded.                            |    ✅    |
| open                 | Boolean to set the initial state (true = expanded, false = collapsed).            |          |
| groupedContent       | Boolean to apply grouped styling to the content area (useful for navigation lists).|          |

To view all the properties of this component, [go to the schema](https://github.com/springernature/elements/blob/main/components/eds-c-accordion/data/eds-c-accordion.schema.json).

{% demo 'Accordion', 'accordionDemo', demos.accordionDemo, component.brand %}

#### Filters (composable with checkboxes)

Use the `eds-c-accordion-composable-with-checkbox` template for filter interfaces. This variant includes the "default" visual styling and supports checkboxes, show more/less functionality, and custom content.

| Name                 | Description                                                                        | Required |
|----------------------|------------------------------------------------------------------------------------|:--------:|
| id                   | Unique identifier for the accordion instance.                                      |    ✅    |
| title                | The title text displayed in the accordion header.                                  |    ✅    |
| iconURL              | URL to the SVG icon used for expand/collapse indicator.                            |    ✅    |
| headingLevel         | The heading level (1-6) for the accordion title.                                   |    ✅    |
| checkboxes           | Array of checkbox objects matching the `eds-c-checkbox` schema.                    |    ✅    |
| variant              | Visual variant (use "default" for filters, FAQs, general content).                 |          |
| open                 | Boolean to set the initial state (true = expanded, false = collapsed).            |          |
| groupedContent       | Boolean to apply grouped styling (recommended: true for checkboxes).               |          |
| enableShowMore       | Boolean to enable show more/less functionality for long content.                   |          |
| showMoreHeight       | Height threshold in pixels before showing "show more" button (default: 300).       |          |
| showMoreText         | Text for the "show more" button (required if enableShowMore is true).              |          |
| showLessText         | Text for the "show less" button (required if enableShowMore is true).              |          |
| dataAttributes       | Array of custom data attributes to add to the accordion container.                 |          |

To view all the properties of this component, [go to the schema](https://github.com/springernature/elements/blob/main/components/eds-c-accordion/data/eds-c-accordion-with-checkbox.schema.json).

To see an example of the filter accordion variant, go to the [Elements Sandbox](https://elements-spr-sandbox.public.springernature.app/scholar-link-search-results).

### Configuration

#### Mobile navigation usage

For mobile navigation, use the basic `eds-c-accordion` template with HTML content:

```html
{% raw %}
{{#with components.mobileAccordion}}
	{{> yourpartials/eds-c-accordion}}
{{/with}}
{% endraw %}
```

Example data:

```json
{
	"id": "nav-products",
	"title": "Products",
	"iconURL": "/img/icons/eds-i-chevron-down-small.svg#eds-i-chevron-down-small",
	"headingLevel": "3",
	"open": false,
	"groupedContent": true,
	"content": "<ul><li><a href=\"/journals\">Journals</a></li><li><a href=\"/books\">Books</a></li></ul>"
}
```

#### Filter accordion usage

For filter interfaces, use the composable `eds-c-accordion-composable-with-checkbox` template:

```html
{% raw %}
{{#with components.filterAccordion}}
	{{> yourpartials/eds-c-accordion-composable-with-checkbox}}
{{/with}}
{% endraw %}
```

Example data:

```json
{
	"variant": "default",
	"id": "content-filter",
	"title": "Content Type",
	"iconURL": "/img/icons/eds-i-chevron-down-small.svg#eds-i-chevron-down-small",
	"headingLevel": "2",
	"open": true,
	"groupedContent": true,
	"checkboxes": [
		{
			"inputType": "checkbox",
			"inputId": "filter-article",
			"name": "contentType",
			"value": "article",
			"label": {
				"text": "Article (664,333)",
				"for": "filter-article"
			}
		}
	]
}
```

#### Custom content with composable template

If you need to further customise the accordion with your own content, you can use the composable base template.

The [eds-c-accordion-composable](https://github.com/springernature/elements/blob/main/components/eds-c-accordion/eds-c-accordion-composable.hbs) template has a `@partial-block`. Use this as a wrapper for your custom template:

```html
{% raw %}
{{#> yourpartials/eds-c-accordion-composable}}
	<!-- Your custom content here -->
	<ul>
		<li>Custom item 1</li>
		<li>Custom item 2</li>
	</ul>
{{/yourpartials/eds-c-accordion-composable}}
{% endraw %}
```

#### groupedContent

Set `groupedContent: true` when the accordion contains form controls like checkboxes or radio buttons, or when it contains navigation lists. This applies appropriate spacing and styling for grouped interactive elements.

```json
"groupedContent": true
```

#### variant property

Use the `variant` property to specify visual styling variants:

- `"default"` - For filters, FAQs, and general content (simpler styling without mobile navigation features)
- Omit `variant` for mobile navigation (uses default mobile nav styling with colored strip)

```json
"variant": "default"
```

#### Checkbox array structure

When using the checkbox variant, each checkbox object must follow the `eds-c-checkbox` schema:

```json
"checkboxes": [
	{
		"inputType": "checkbox",
		"inputId": "filter-article",
		"name": "contentType",
		"value": "article",
		"label": {
			"text": "Article (664,333)",
			"for": "filter-article"
		}
	}
]
```

#### Show more / Show less button

The filter accordion variant supports progressive disclosure of lengthy content with a "Show more / "Show less" button. This is useful for filter panels or long lists where you need to show only the most relevant options initially.

**Note:** This feature is only available when using the filter variant (`variant: "default"`).

##### How it works

Content is initially limited to a configurable height with a default of 300px. If content exceeds this threshold, the JavaScript will add a "Show more" button.
This button then switches between "Show more" and "Show less", depending on which option is currently selected.

Without JavaScript, all content is visible and no button appears.

```json
{
	"enableShowMore": true,
	"showMoreHeight": 300,
	"showMoreText": "Show more",
	"showLessText": "Show less"
}
```

| Property       | Description                                      | Required |
|----------------|--------------------------------------------------|:--------:|
| enableShowMore | Boolean to enable the show more/less feature.    |          |
| showMoreHeight | Height threshold in pixels (default: 300).       |          |
| showMoreText   | Text displayed when content is collapsed.        |    ✅    |
| showLessText   | Text displayed when content is expanded.         |    ✅    |

If `enableShowMore` is true, then `showMoreText` and `showLessText` are required.

Example:

```json
{
	"id": "content-filter",
	"title": "Content Type",
	"iconURL": "/img/icons/eds-i-chevron-down-small.svg#eds-i-chevron-down-small",
	"headingLevel": "2",
	"groupedContent": true,
	"enableShowMore": true,
	"showMoreHeight": 300,
	"showMoreText": "Show more",
	"showLessText": "Show less",
	"checkboxes": [...]
}
```

### JavaScript

To enable accordion functionality, import and initialize the component:

```javascript
import {EdsCAccordion} from '@springernature/elements/components/eds-c-accordion/js/eds-c-accordion';

// Initialize all accordions on the page
const accordion = new EdsCAccordion('data-eds-c-accordion');
accordion.init();

// Or with custom options
const accordion = new EdsCAccordion('data-eds-c-accordion', {
	showMoreHeight: 250  // Override default height threshold
});
accordion.init();
```



### Accessibility

You must configure the correct semantic heading level for section headings.

ARIA attributes (`aria-expanded`, `aria-controls`, `aria-labelledby`) are supported and must be used.

The component also supports keyboard navigation, clear visual focus indicators and announces state changes to assistive technology.