Sections

Create toggles in content

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 data-element="toggles" attribute to the list and a data-title attribute to each list item. For example:

<ul data-element="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>
</ul>

Where:

  • The data-element="toggles" attribute 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.

Because data attributes are used, you will need to ensure that the allow unsafe HTML setting is enabled within 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 plugin page:

  • <ul data-element="toggles">
      <li data-title="The first toggle title">
        <p>Mauris ipsum. Nulla metus metus, ullamcorper vel, tincidunt sed, euismod in, nibh. Quisque volutpat condimentum velit. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nam nec ante. Sed lacinia, urna non tincidunt mattis, tortor neque adipiscing diam, a cursus ipsum ante quis turpis.</p>
      </li>
      <li data-title="The second toggle title">
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
      </li>
      <li data-title="The third toggle title">
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer congue justo a metus bibendum dapibus. In imperdiet interdum tincidunt. Nam odio dolor, hendrerit vel eros non, viverra pellentesque tellus. Proin ac elit in leo faucibus gravida. Donec ut neque non augue porttitor mollis a quis eros.</p>
      </li>
    </ul>

Enabling accordion functionality

Enabling the accordion option in the Toggles plugin 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:

<ul data-element="toggles" data-accordion="true">
  <li data-title="The first toggle title">...</li>
  <li data-title="The second toggle title">...</li>
  <li data-title="The third toggle title">...</li>
</ul>
  • <ul class="toggles" data-accordion="true">
      <li data-title="The first toggle title">
        <p>Mauris ipsum. Nulla metus metus, ullamcorper vel, tincidunt sed, euismod in, nibh. Quisque volutpat condimentum velit. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nam nec ante. Sed lacinia, urna non tincidunt mattis, tortor neque adipiscing diam, a cursus ipsum ante quis turpis.</p>
      </li>
      <li data-title="The second toggle title">
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>
      </li>
      <li data-title="The third toggle title">
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer congue justo a metus bibendum dapibus. In imperdiet interdum tincidunt. Nam odio dolor, hendrerit vel eros non, viverra pellentesque tellus. Proin ac elit in leo faucibus gravida. Donec ut neque non augue porttitor mollis a quis eros.</p>
      </li>
    </ul>

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 */
.toggle-title {
  color: red;
}

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

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:

Additional features like custom icons can be included in a custom micro-template, as seen in the Tabs example.

You could include the micro-template within the Article page template (article_page.hbs) or one that’s globally available, like the Footer (footer.hbs). The micro-template in this example has an id of tmpl-custom-tabs so to apply this to a set of tabs in your content you’d update your list to include a reference to the template:

<ul data-element="toggles" data-template="custom-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>
</ul>

Questions or feedback about this guide? Let us know