Accordions (previously called toggles in our documentation) show a list of section titles that visitors can expand to read more. They help minimize scrolling and, when used properly, let visitors find the content that’s relevant to them quickly and easily. They work well for FAQs, troubleshooting steps and optional guidance.
It’s important to consider what the best approach for structuring your article content is. For example, if the page is long but visitors need most or all of the content on the page a navigation element like a table of contents or sidebar menu may be more appropriate.
The Zendesk article editor now includes native accordions that you can add and edit straight from the toolbar, and our themes style them to match the rest of your help center. We recommend using them for all new content. The list-based toggles used in earlier versions of our themes are still supported, so existing articles don’t need to change. You’ll find their instructions in the Legacy elements tab.
Native article components are supported in version 4.0.0 or later of our themes. If you’re using an earlier version, use the legacy elements instead.
Adding accordions
-
Create a new article or edit an existing one in your help center or Knowledge admin, and place your cursor where the accordion should appear.
-
Click the Article components button in the editor toolbar and select Accordion.
-
Enter a title for the first section, followed by the content that visitors will see when they expand it.
-
Click the Add section icon (+) in the accordion toolbar to add another section. Use the Move up and Move down icons to reorder sections, and the Remove icon to delete one.
-
Click Save.
To move an accordion, hover over it and drag the handle. To remove it, click the handle to select the accordion and press Delete.
Native accordion
The editor creates this markup for you. Each section is a standard <details> element, so accordions work even if scripts are unavailable.
Opening sections by default
Sections start collapsed unless they’re saved with the open attribute. To open a particular section when the page loads, add a data-initial attribute with the section’s position (starting from 0) to the accordion using the editor’s HTML (source code) view:
<div class="wysiwyg-disclosure" data-initial="0">
...
</div>Keeping one section open at a time
By default, visitors can expand as many sections as they like. Add data-accordion="true" to the accordion using the HTML view to make sure only one section is open at a time. If one is already open, expanding another will cause it to close:
<div class="wysiwyg-disclosure" data-accordion="true">
...
</div>To apply these options to every accordion in your help center, set them in a script in your Document head template (document_head.hbs) instead:
<script>
window.Theme = window.Theme || {};
window.Theme.disclosures = { accordion: true };
</script>Linking to a section
Our themes give each section an id based on its title. For example, a section titled “How do I reset my password?” can be linked to with #how-do-i-reset-my-password. Following the link opens that section and scrolls to it. A link to the id of any element inside a section, such as a heading, works the same way.
Styling accordions
The brand color, text color, border color and margin can be changed in the Accordions section of the visual builder’s Formatting elements panel.
You can also write your own custom CSS, for example:
/* Change the color of a section title to red */
.content .wysiwyg-disclosure summary {
color: red;
}
/* Change the color of text in an expanded section to blue */
.content .wysiwyg-disclosure-content {
color: blue;
}Using a custom micro-template
For the more adventurous among you, you can create your own custom micro-template. A custom template replaces the default rendering for both native accordions and legacy toggles.
A custom template allows you to change not just the appearance of the accordions, but their underlying HTML structure and behavior. Below is an example of a custom accordions template that you could use to change the size and appearance of the sections:
Large, custom toggles with icons
Additional features like custom icons can be included in a custom micro-template.
Version 4.0.0 of our themes includes a ready-made accordions template, commented out, in the Document head template (document_head.hbs). Remove the comment tags around the tmpl-accordions template to use it as a starting point. The accordions script looks for a micro-template with an id of accordions (or toggles, for compatibility with earlier versions) by default, so adding one to the Document head, Article page (article_page.hbs) or Footer (footer.hbs) template will ensure that it’s used for all accordions within your article content.
<script type="text/template" id="tmpl-accordions">
...
</script>The template receives the accordion’s id, the index of the initial section, the accordion and activeClass options and a list of children. Each child has an id, a title, the section’s content as innerHTML and, for native accordions, whether it was saved open.