Foundation
Jump to Nav

# Accordion

JavaScript

Accordions are elements that help you organize and navigate multiple documents in a single container. They can be used for switching between items in the container.

## Basics

The container for an accordion needs the class `.accordion`, and the attribute `data-accordion`. Note that in these examples, we use a `<ul>`, but you can use any element you want.

    <ul class="accordion" data-accordion></ul>

Inside the accordion, place a series of panes with the class `.accordion-item` and the attribute `data-accordion-item`. To mark which pane should be open by default, add the class `.is-active` to that pane.

Each pane has a title, an `<a>` with the class `.accordion-title`, and a content area, an element with the class `.accordion-content` and the attribute `data-tab-content`.

    <ul class="accordion" data-accordion>
      <li class="accordion-item is-active" data-accordion-item>
        <a href="#" class="accordion-title">Accordion 1</a>
        <div class="accordion-content" data-tab-content>
          I would start in the open state, due to using the `is-active` state class.
        </div>
      </li>
      <!-- ... -->
    </ul>

Once you put it all together, here's what you get!

- Accordion 1

  Panel 1. Lorem ipsum dolor

  Nowhere to Go
- Accordion 2
- Accordion 3
  Pick a date!

## Advanced Options

### Multi-expand

By default, only one pane of an accordion can be open at a time. This can be changed by setting the `multiExpand` option to `true`.

    <ul class="accordion" data-accordion data-multi-expand="true">
      <!-- ... -->
    </ul>

- Accordion 1
  Panel 1. Lorem ipsum dolor
- Accordion 2
  Panel 2. Lorem ipsum dolor
- Accordion 3
  Panel 3. Lorem ipsum dolor

### All Closed

By default, at least one pane in an accordion must be open. This can be changed by setting `allowAllClosed` option to `true`.

    <ul class="accordion" data-accordion data-allow-all-closed="true">
      <!-- ... -->
    </ul>

- Accordion 1
  Panel 1. Lorem ipsum dolor
- Accordion 2
  Panel 2. Lorem ipsum dolor
- Accordion 3
  Panel 3. Lorem ipsum dolor

## Accordion and URLs

### Browser history

When the `data-deep-link` option is set to `true`, the current state of the accordion is recorded by adding a hash with the accordion panel ID to the browser URL when a accordion opens. By default, accordion replace the browser history (using `history.replaceState()`). Modify this behavior by using attribute `data-update-history="true"` to append to the browser history (using `history.pushState()`). In the latter case the browser back button will track each click that opens a accordion panel.

By using deep linking (see below), the open state of a page's tabset may be shared by copy-pasting the browser URL.

### Deep linking

Add the attribute `data-deep-link="true"` to a accordion to:

- modify the browser history when a accordion panel is clicked
- allow users to open a particular accordion panel at page load with a hash-appended URL

    <ul class="accordion" data-accordion data-deep-link="true" data-update-history="true" data-deep-link-smudge="true" data-deep-link-smudge="500" id="deeplinked-accordion">
      <li class="accordion-item is-active" data-accordion-item>
        <a href="#deeplink1" class="accordion-title">Accordion 1</a>
        <div class="accordion-content" data-tab-content id="deeplink1">
          Panel 1. Lorem ipsum dolor
        </div>
      </li>
      <li class="accordion-item" data-accordion-item>
        <a href="#deeplink2" class="accordion-title">Accordion 2</a>
        <div class="accordion-content" data-tab-content id="deeplink2">
          Panel 2. Lorem ipsum dolor
        </div>
      </li>
      <li class="accordion-item" data-accordion-item>
        <a href="#deeplink3" class="accordion-title">Accordion 3</a>
        <div class="accordion-content" data-tab-content id="deeplink3">
          Panel 3. Lorem ipsum dolor
        </div>
      </li>
    </ul>

- Accordion 1
  Panel 1. Lorem ipsum dolor
- Accordion 2
  Panel 2. Lorem ipsum dolor
- Accordion 3
  Panel 3. Lorem ipsum dolor

For example, http://example.com/#deeplink3 will open the third accordion panel at page load. This example will open a new browser tab and scroll you to the open accordion panel.

When linking directly to a accordion panel, it might not be obvious that the content appears within a accordion panel. An additional attribute `data-deep-link-smudge` rolls the page up slightly after deep linking (to a horizontal accordion) so that the accordion is at the top of the viewport.

    <ul class="accordion" data-deep-link="true" data-deep-link-smudge="true" data-deep-link-smudge-delay="600" data-accordion id="deeplinked-accordion-with-smudge">

## Sass Reference

### Variables

The default styles of this component can be customized using these Sass variables in your project's settings file.

Name | Type | Default Value | Description
--- | --- | --- | ---
`$accordion-background` | Color | `$white` | Default background color of an accordion group.
`$accordion-plusminus` | Boolean | `true` | If `true`, adds plus and minus icons to the side of each accordion title.
`$accordion-title-font-size` | Number | `rem-calc(12)` | Font size of accordion titles.
`$accordion-item-color` | Color | `$primary-color` | Default text color for items in a Menu.
`$accordion-item-background-hover` | Color | `$light-gray` | Default background color on hover for items in a Menu.
`$accordion-item-padding` | Number or List | `1.25rem 1rem` | Default padding of an accordion item.
`$accordion-content-background` | Color | `$white` | Default background color of tab content.
`$accordion-content-border` | Color | `1px solid $light-gray` | Default border color of tab content.
`$accordion-content-color` | Color | `$body-font-color` | Default text color of tab content.
`$accordion-content-padding` | Number or List | `1rem` | Default padding for tab content.

### Mixins

We use these mixins to build the final CSS output of this component. You can use the mixins yourself to build your own class structure out of our components.

#### accordion-container

    @include accordion-container;

Adds styles for an accordion container. Apply this to the same element that gets `data-accordion`.

#### accordion-item

    @include accordion-item;

Adds styles for the accordion item. Apply this to the list item within an accordion ul.

#### accordion-title

    @include accordion-title;

Adds styles for the title of an accordion item. Apply this to the link within an accordion item.

#### accordion-content

    @include accordion-content;

Adds styles for accordion content. Apply this to the content pane below an accordion item's title.

## JavaScript Reference

### Initializing

The file `foundation.accordion.js` must be included in your JavaScript to use this plugin, along with `foundation.core.js`. This plugin also requires these utility libraries:

- `foundation.util.keyboard.js`

- `foundation.util.motion.js`

### Foundation.Accordion

Creates a new instance of an accordion.

    var elem = new Foundation.Accordion(element, options);

Fires these events: Accordion#event:init

Name | Type | Description
--- | --- | ---
`element` | jQuery | jQuery object to make into an accordion.
`options` | Object | a plain object with settings to override the default options.

### Plugin Options

Use these options to customize an instance of Accordion. Plugin options can be set as individual data attributes, one combined `data-options` attribute, or as an object passed to the plugin's constructor. Learn more about how JavaScript plugins are initialized.

Name | Type | Default | Description
--- | --- | --- | ---
`data-slide-speed` | `number` | `250` | Amount of time to animate the opening of an accordion pane.
`data-multi-expand` | `boolean` | `false` | Allow the accordion to have multiple open panes.
`data-allow-all-closed` | `boolean` | `false` | Allow the accordion to close all panes.
`data-deep-link` | `boolean` | `false` | Allows the window to scroll to content of pane specified by hash anchor
`data-deep-link-smudge` | `boolean` | `false` | Adjust the deep link scroll to make sure the top of the accordion panel is visible
`data-deep-link-smudge-delay` | `number` | `300` | Animation time (ms) for the deep link adjustment
`data-update-history` | `boolean` | `false` | Update the browser history with the open accordion

### Events

These events will fire from any element with a Accordion plugin attached.

Name | Description
--- | ---
`deeplink.zf.accordion` | Fires when the zplugin has deeplinked at pageload
`down.zf.accordion` | Fires when the tab is done opening.
`up.zf.accordion` | Fires when the tab is done collapsing up.

### Methods

#### toggle

    $('#element').foundation('toggle', $target);

Toggles the selected content pane's open/close state.

Name | Type | Description
--- | --- | ---
`$target` | jQuery | jQuery object of the pane to toggle (`.accordion-content`).

#### down

    $('#element').foundation('down', $target, firstTime);

Opens the accordion tab defined by `$target`.

Fires these events: Accordion#event:down

Name | Type | Description
--- | --- | ---
`$target` | jQuery | Accordion pane to open (`.accordion-content`).
`firstTime` | Boolean | flag to determine if reflow should happen.

#### up

    $('#element').foundation('up', $target);

Closes the tab defined by `$target`.

Fires these events: Accordion#event:up

Name | Type | Description
--- | --- | ---
`$target` | jQuery | Accordion tab to close (`.accordion-content`).

#### destroy

    $('#element').foundation('destroy');

Destroys an instance of an accordion.

Fires these events: Accordion#event:destroyed