Evaluating the Usability of Collapsible Sections (or jQuery’s Content Toggle)

After my post on Organizing Page-Level Content, a couple of people asked me about the usability of collapsible sections, also known as content toggles or dropdown hotspots. These are sections that are collapsed upon initial display and then expand when clicked.

You can implement collapsible sections in several ways. In Flare, you can insert drop-down hotspots from a quick button on the ribbon. In Drupal, you can use the Collapse Text module. In WordPress, you can use the Collapse-O-Matic plugin. The theme I’m using (Canvas from woothemes) has collapsible sections built directly in.

You can also code the sections directly using jQuery through the Toggle method. For example, if you wanted to toggle a section with the ID “section” so it appeared in an expand/collapse state, you would insert a reference to the jQuery library in script tags, and then insert another script like this:


In the above code, #section is the unique ID of the element you want to toggle. (Including the twisting arrows is more complex.)

Wikipedia’s mobile pages use collapsible sections by default. Here’s an example if you want to explore collapsible sections a bit more.

Problems with the Collapsible Sections

Collapsible sections are cool but somewhat problematic. One person commented:

I really like collapsible sections, but I’ve encountered some usability issues with them (searches won’t look in collapsed sections, users might not know which section contains the info that they want). It would be great if you could search for something and the search result would auto-expand the correct section, but I haven’t seen that.

Another person asked via email:

How have users reacted to having to use progressively disclose the information by clicking? I ask because I received negative feedback when I incorporated togglers in Flare at a previous company.

Are collapsible sections really a best practice for help documentation, or do they just present more problems?

Overall, I think collapsible sections provide a strong advantage in organizing content and should probably be followed despite the drawbacks. Collapsible sections do all of the following:

  • Collapsible sections compress a lot of information into a small space that users can visually scan in a quick way.
  • Collapsible sections hide the length of information so that the content looks simpler and lighter to users (until they expand all the sections to see just how much content is there).
  • Collapsible sections allow you to include content in a way that adjusts to the user’s need. If users want more information, they click the link to read more. But if not, users aren’t burdened by all the content.
  • Collapsible sections allow users to interact with the content so they’re choosing what they want to learn.

If you trend toward longer pages, collapsing the sections can provide a huge win for navigation and usability.

Now for the downside. If a user searches for a keyword that’s buried inside a collapsed section, the user might be bewildered by not seeing the highlighted keyword on the page, because the collapsed section remains collapsed even in search results. (Seems like there would be an easy workaround for this, but I don’t know it.)

Keep in mind that Google doesn’t highlight keywords in search results. Google bolds keyword matches in the search engine results page summary, but when you click the result link to view the page, nothing is highlighted or bolded. So it seems a bit unfair to require help to highlight keyword matches on the full-page view.

Another drawback may be with content re-use. With Flare, you can store all of these collapsed as snippets and re-use the snippets, but what if you’re using another tool or platform that doesn’t have a snippets-like feature? You may be limited to only reusing larger chunks of content.

Finally, some users may find it annoying to have to expand content before being able to read it.

In looking at help systems, I don’t see many tech writers using collapsible sections. This may be due to limitations with the tech writer toolset, but I think a greater reason is that most topics are short, and the TOCs are massive. We’re still writing in the book paradigm rather than following the Every Page Is Page One style. As soon as you switch to a style that favors longer help topics, collapsible sections are about the only way to avoid intimidating the user with too much text.

What’s your verdict on collapsible sections?

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • http://www.mardahl.dk Karen Mardahl

    You need to look into ARIA to complete the picture. JQuery can make Rich Internet Applications. You just need to add Accessible in front of that: Accessible Rich Internet Applications, or ARIA.

    “Simplifying the user interface by collapsing sections may improve usability for all, including those with cognitive or developmental disabilities.” That is a quote I took from this page – http://www.w3.org/WAI/PF/aria/states_and_properties#aria-expanded – which describes the WAI-ARIA state called aria-expanded, which would be part of an accessible solution to this topic.

    Good links about ARIA are:
    WAI-ARIA authoring practices: http://www.w3.org/TR/wai-aria-practices/
    Using ARIA in HTML: http://www.w3.org/TR/aria-in-html/
    Overview page: http://www.w3.org/WAI/intro/aria
    A nice intro: http://www-03.ibm.com/able/resources/wai_aria_intro.html

    • http://idratherbewriting.com Tom Johnson

      Karen, thanks for adding the usability angle for people with disabilities. I’m glad to hear that jQuery can be an advantage in those situations. I appreciate all the links. (By the way, my spam filter auto tags any comments with more than 5 links, so I just saw this in my approve queue and approved it.) This research makes me think collapsing sections are even cooler than I originally thought.

  • HoetTC

    From a comparison exercise recently run of various help systems, I could see a clear distinction where dropdowns were either over-used or not used at all.

    My 2 cents – Use with moderation. Drop-downs on their own solve no paradigm, but are best used in conjunction with other controls.
    One particular rule I stick to is to avoid having drop-downs within drop-downs. If this is required, consider breaking the content into different topics.

    • http://idratherbewriting.com Tom Johnson

      HoetTC, I definitely agree that drop-downs within drop-downs are a no-no. Just like with Prezi, it can be easy to manipulate a nifty tool into a usability nightmare.

  • http://everypageispageone.com Mark Baker

    There is another downside to collapsible sections, which is that they prevent the reader from scanning the material. That makes it harder for the reader to home in on the piece of information they are looking for. If I have to open a bunch of closed sections to scan inside them, that is really going to annoy me.

    The use case of collapsible sections seems to rest on two presumptions. The first is that the reader is reading sequentially (if not, then a mini TOC at the topic of the topic serves the same purpose) and that at certain points some readers may want more in depth material and others may not.

    Those situations certainly occur. For instance, in a procedure, some readers may know how to perform detailed operations like opening a file and others may not. Having some mechanism by which people who don’t know how to open a file can click on “open a file” in the high level procedure and get the procedure for opening a file makes sense.

    But putting my manager/content strategist hat on, I don’t think I would be willing to give this tool out to writers to use willy nilly, because I think it will get used in all sorts of inappropriate ways that do more harm than good. Rather, I would reserve it for use in a structured writing system where the writer would simply supply semantic markup, such as

    Open a new file.

    and the publishing system would pull in the procedure for opening a file (automatic reuse!) and put it in a collapsible section at the appropriate place.

    In case the editor eats the markup above, here is the escaped version:

    <step><task>Open a new file.</task></step>

    • http://idratherbewriting.com Tom Johnson

      Mark, thanks for commenting. Re scanning, I think collapsed sections paradoxically facilitate as well as hinder scanning. They facilitate scanning because users can easily look at the headings and click the one they want (in that sense, collapsed sections don’t force a sequential order). But just looking at headings provides only a minimal amount of information, so it makes it harder to get at the content too.

      Still, it’s dead simple to add an Expand All or Collapse All button at the top, like I did with my sample code. This would easily accommodate the user who wants to see everything in one glance without expanding each little section.

      Although Wikipedia offers a mini-TOC atop each page, users still get intimidated by large walls of text. When I’ve implemented collapsing sections, the response has usually been positive.

      • Seth

        Since it’s simple to add an Expand and Collapse All button, do you have any thoughts about why a documentation team might decide to remove that feature?

        The following link provides an example of content that used to offer the reader Expand and Collapse All options, but someone made the decision to remove that capability in the latest version of the site:


        I think that content provides a valid example of the downside to collapsible sections that Mark pointed out above. Trying to find specific pieces of info on that page or any similar pages in that documentation set can be an annoying process.

  • http://www.enjoytechnicalwriting.com Vinish Garg


    I agree with HoetTC that whether to use collapsible text (accordion controls or custom jquery code) or not should be a thought-out process rather than a Yes/No right away.

    For example one, using such collapsible options can be extremely effective for ‘Glossary’ ‘FAQs’ pages, or for note/caution for specific users based on their roles. Two, when we use CMS such as Drupal or WordPress to develop a product support center, we can use this collapsible/expandable features for additional sections such as ‘Most Frequently Asked Questions’ and ‘Top Rated Questions’. And three, using accordion controls can be a good strategy when we publish topics for a mobile device where the display size is comparatively smaller.

    For not being indexed in search, I found that the expanded text is indexed by Google Search. For example if you add three sections for each tab and add corresponding feeds link to each tab. the feeds text is indexed by Google. I am sure these are indexed by CMS specific search also, such as standard and default search function by WordPress or Drupal. I am not sure of Flare or RoboHelp though.

    Personally, I foresee a greater use of such features (accordion controls, HTML5/CSS3 for responsive themes, custom theme such as for sidebar and post content area).

    • http://idratherbewriting.com Tom Johnson

      Vinish, you present some excellent use cases for the expand/collapse features. I think the features definitely fit unquestionably with a glossary, FAQ, or definition page. Using them with content requires more thought. You’re right that we should be careful in using them rather than wantonly implementing the tech just because we can. Thanks for pointing this out.

      By the way, I’m not sure, but maybe if you implement a hidden section by using display:none in your CSS rather than jQuery’s $(.element).hide feature, Google might not index the content. Not sure, but I did read that somewhere.

  • http://daktronics.com Dan Schulte

    Your blog is always interesting, and this one is especially timely. We were just looking at a good way to provide a short list of sequential steps, but keep the list easy to scan through by only providing the details to each step as needed. One suggestion was that eacy step would have a link to another file, but then you always have to navigate back to the original article. I was just starting to consider the idea of expandable content when I saw your blog. Then Mark added another great idea by suggesting that the expaned content could be a separate (and reusable) file in itself.

    In my company, I am trying to cultivate the idea of transitioning content from print to EPPO type Web articles. So I love to read both your blog and Mark’s, and see the comments. Keep them coming!

    • http://idratherbewriting.com Tom Johnson

      Dan, thanks for the comment. I just added another post with some sample code for implementing the collapse/expand buttons.

      Storing the content separately and inserting it dynamically sounds like a neat idea. I’m wondering exactly how you’d do that. If you’re running on a PHP site, you could use PHP includes. Or with JavaScript, you could have a bunch of functions that inserted the HTML.

  • Tammy

    I find them quite useful. Sometimes there is a lot to say about a page or a topic, and chunking isn’t always a good option for context-sensitivity. Using collapsible text can help readers find quickly without a lot of scrolling or skimming through what they don’t want or need. Of course, the links must be well-named (just like regular hyperlinks) so the reader knows what to expect when clicking the link.

    I also use them for explanatory information that not everyone needs but that some users require. Advanced users can stick to the steps, and those who need more background can still get what they need.

    • http://idratherbewriting.com Tom Johnson

      Thanks Tammy. I’m glad to hear you’ve had a lot of success with collapsing/expanding sections. I do like the use case of providing more in-depth information for advanced users. I think more tech writers should take advantage of this functionality in help systems.

  • Matt

    I’m curious about these collapsible sections and analytics, have you ever heard tell of people using collapsibles as ‘event clicks’ for tracking which content is getting the most traffic?

    • http://idratherbewriting.com Tom Johnson

      I haven’t heard of integration analytics with this behavior, but it might be interesting. I’m not sure exactly how to code that. I think you’d have to pass a custom ID for each section or something. Otherwise how would you tell what the user clicked?

  • John Garison

    Hi Tom,

    I have long considered collapsible content as the Holy Grail of tech comm for most of the reasons cited above. I have used them, but it’s been just too darned painful to do so.

    I got my hopes up when I heard that HTML5 was introducing the tag (provides a heading that can be clicked on to expand/collapse the details as required) and its companion tag (specifies additional details that the user can view or hide on demand).

    They look easy to implement in documents, and there’s no JavaScript … Not sure how well they will play with others regarding searchability, but if they are just standard text tags, perhaps this bodes well for eliminating that objection.

    Here’s a chart showing which browser versions are scheduled to support this:


    Not so many at the moment, but the future looks rosy.

    My 2¢,


    • http://idratherbewriting.com Tom Johnson

      Thanks John. I forgot that HTML5 introduces this as a feature. I think that makes a strong case for the utility of collapsing sections. When you said that it’s too painful to use these sections, I’m not sure what you mean. Do too many content management systems strip out javascript? Does it get confusing when you have so much content aggregated on one page? Do these widgets make reuse problematic? Is the code itself confusing? Is it too tedious to tag paragraphs with a custom div tag?

      I did just post a sample code showing how to implement collapsing/expanding sections here. Obviously the CSS and JS would be referenced at the top of the page (as well as jQuery) rather than embedded directly. I hope the sample code is helpful.

      • John Garison

        Hi Tom,

        What I meant was that using the JS-based expando options – at least the three that I tried – was very difficult and time-consuming to set up in the code. I was using Dreamweaver, and copying and pasting the code snippets, then copying and pasting the text snippets and going back and twiddling all the syntax-y bits was just a pain. Took too long, was very persnickety, and just not worth the effort. I was using it to create a calendar-like webpage – lots of events on one page, click the title to see the details sort of thing.

        After I moved on one of the very first things the new guy did was to ditch that approach,

        I haven’t used the new HTML5 commands yet … hope to when there’s a way to display them!


        • John Garison

          Addendum: My experience is 5+ years ago – I would hope someone has developed a better implementation. I looked at your code samples, and it looks easier than I remember. Nice site to play around with, too!

          • http://idratherbewriting.com Tom Johnson

            jQuery made everything a heck of a lot simpler, in my opinion. And if you use Dreamweaver or another tool to auto-create them, the result looks impossibly complicated. For example, I used to use Dreamweaver to create image rollovers when they were the big thing. The resulting code was like a giant wall of sanskrit to me. But if I were to write it myself, it would be much simpler, I think.

            Anyway, there are larger challenges. Most CMS tools strip out JavaScript, so even if you write yourself, you have the challenge of actually using it.

  • Pingback: Sample Expand and Collapse Code with Twisting Buttons | I'd Rather Be Writing()

  • Pingback: Sample Expand and Collapse Code with Twisting Buttons » eHow TO...()

  • Lucia

    Hi Tom,

    There’s really no workaround for the situation below, to make the dropdown expand when a searched term is inside it?

    “I really like collapsible sections, but I’ve encountered some usability issues with them (searches won’t look in collapsed sections, users might not know which section contains the info that they want). It would be great if you could search for something and the search result would auto-expand the correct section, but I haven’t seen that.”

  • Pingback: Does DITA Encourage Authors to Fragment Information into a Million Little Pieces? | I'd Rather Be Writing()