Creating toggles

Collapsible toggles and accordions can be used to make your article content easier to navigate and read. They help minimize scrolling and, when used properly, allow visitors to find content that’s relevant to them quickly and easily.

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.

Adding toggles to article content

The first step is to create a numbered or bulleted list in your article where each list item contains the content that will be contained within its own collapsible toggle section. If you have a lot of content to display in each toggle, or content that contains headings and other custom elements, we recommend using the Source Code view within the article editor.

The list itself will be a <ol> or <ul> element, with child list items represented as <li> elements.

Once you’ve added all of your content to the list add a class name of js-toggles to the list and a data-title attribute to each list item. For example:

<ul class="js-toggles">
  <li data-title="The first toggle title">...</li>
  <li data-title="The second toggle title">...</li>
  <li data-title="The third toggle title">...</li>


  • The .js-toggles class name specifies that we’d like to convert this list into dynamic toggles.
  • The data-title attribute specifies the title for each toggle.
  • The content of each list item is converted into its own collapsible toggle section.

The default toggles style as well as an alternative method for specifying toggle titles can be found on the Toggles extension page.

If data attributes are used you will need to ensure that the allow unsafe HTML setting is enabled within Zendesk Guide.

This approach ensures a separation between your content and how it’s displayed to visitors. If you ever decide to switch off toggles for a given list, change themes or export your content you’ll see a simple, uncontaminated list.

The default toggles styles can be seen on the Toggles extension page.

Enabling accordion functionality

Enabling the accordion option in the Toggles extension ensures that only one toggle within a group is open at a time. If one is already open, expanding another will cause it to close.

The easiest way to enable this option is using the data-accordion="true" attribute:

Toggles behaving as an accordion
View code
<ul class="js-toggles" data-accordion="true">
  <li title="Android">
    <p>Android is a mobile operating system based on a modified version of the Linux kernel and other open source software, designed primarily for touchscreen mobile devices such as smartphones and tablets. Android is developed by a consortium of developers known as the Open Handset Alliance and commercially sponsored by Google. It was unveiled in 2007, with the first commercial Android device launched in September 2008.</p>
  <li title="iOS">
    <p>iOS is a mobile operating system created and developed by Apple Inc. exclusively for its hardware. It is the operating system that presently powers many of the company's mobile devices, including the iPhone, and iPod Touch; it also powered the iPad prior to the introduction of iPadOS in 2019. It is the second most popular mobile operating system globally after Android. It is the basis for other operating systems made by Apple Inc, like iPadOS, tvOS, and watchOS.</p>
  <li title="Windows">
    <p>Windows 10 Mobile is a discontinued mobile operating system developed by Microsoft. First released in 2015, it is a successor to Windows Phone 8.1, but was marketed by Microsoft as being an edition of its PC operating system Windows 10. Windows 10 Mobile aimed to provide greater consistency with its counterpart for PCs, including more extensive synchronization of content, the ability to to connect devices to an external display and use a desktop interface with mouse and keyboard input support.</p>

Styling toggles

If you’d like to give your toggles their own unique look-and-feel there are a couple of options. You can write your own custom CSS, for example:

/* Change the color of a toggle title to red */
.content .toggle-title {
  color: red;

/* Change the color of text in a collapsible toggle section to blue */
.content .toggle-title ~ .collapse {
  color: blue;

Using a custom micro-template

Or for the more adventurous among you, you can create your own custom micro-template.

A custom template allows to to change not just the appearance of the toggles, but their underlying HTML structure and behavior. Below is an example of a custom toggles template that you could use to change the size and appearance of the toggles:

Large, custom toggles with icons

Additional features like custom icons can be included in a custom micro-template.

The Toggles extension looks for a micro-template with an id of toggles by default, so adding one to Article page template (article_page.hbs) or the globally available Footer template (footer.hbs) will ensure that it’s used for all toggles within your article content.

<ul class="js-toggles">
  <li data-title="The first toggle title">...</li>
  <li data-title="The second toggle title">...</li>
  <li data-title="The third toggle title">...</li>

<template id="tmpl-toggles">

Questions or feedback about this article? Let us know