Summary

Use this when you need to show users one or more small snippets of a larger body of text in order to keep the user interface lightweight and scannable.

This pattern includes both revealing the rest of the text on the same screen, and linking to another screen for the full text.

Status

API status: general
Web resource key: com.atlassian.auiplugin:aui-expander
AMD Module key: N/A
Experimental API: 5.1
General API: 5.8

Examples

Content title

What happens when you add a shiny new browser to a stack of already-disagreeing citizens? You’ll inevitably find some bugs. This is the story of how we found a rendering quirk and how the Atlassian frontend team found and refined the fix. The Problem The Atlassian User Interface (AUI) library has just finished an IE10 sprint to get our library prepped and ready for the newest member of the browser family. While IE10 seems generally quite good, we found a couple of problems due to IE10 dropping conditional comments; plus some undesirable behaviours.

Code

HTML

Regular expander

To use regular expander through HTML you need to create:

  • A content container, typically a div element with a aui-expander-content class and a unique id.
  • An expander trigger, ideally a button for accessibility reasons, with a aui-expander-trigger class and an aria-controls attribute set to the unique id of the content container.

If you wish to have the text inside the trigger replaced, you must supply a data-replace-text attribute. This text will serve as the replacement for the expander's next state. The expander will find the most deeply nested tag inside and substitute the text within it.

Initially opened expander

To create an expander that is initially opened via HTML, you need to apply the expanded class to the content container.

Keep in mind that the button's content corresponds to the initial state of the expander. Therefore, in this example, it's for the expanded state of the expander.

The data-replace-text will be used for the collapsed state.

Reveal text

Expander also allows us to display a portion of the text initially. The remaining text can be revealed by interacting with the expander. This is particularly useful when dealing with long blocks of text where you want to provide the user with the option to view more information if they choose.

To create this, you need to follow these steps:

  • Enclose the expander's trigger within the content.
  • Add the aui-expander-reveal-text class to the trigger.
  • Use CSS to set a minimum height for the expander content. This will serve as the limit for the text.

Soy

Regular expander

Reveal text

Options

Trigger

Class Description Required
aui-expander-trigger This is the necessary class to apply when using a trigger
aui-expander-reveal-text Necessary class when implementing the expander reveal text pattern
Attribute Description Required
aria-controls The id of the content that this trigger expands/hides
data-replace-text The text that replaces the trigger's content after the expanding/collapsing the component
data-replace-selector deprecated Selector to the element that will get get the text from data-replace-text replaced
data-collapsible Defines whether the component can be collapsed or not

Content

Class Description Required
aui-expander-content This is the necessary class to apply when using a expander's content
Attribute Description Required
id Unique id that triggers must match to work properly
aria-expanded deprecated Old version of setting the content to be initially expanded

Trigger

Param Description Required
content The content of the trigger
contentId The id of the content that this trigger expands/hides
id Unique id of the trigger
replaceText Text replacement for trigger button after invokation
collapsible Whether or not the trigger will collapse the expander after it is expanded
replaceSelector deprecated Selector for element which text will be replaced with the initial trigger text when it is invoked
tag This tag is used for the trigger, with the default being a button. Refer to the A11Y guidelines for more information

Content

Param Description Required
id Unique id that triggers must match to work properly
content Content of the expander
initiallyExpanded Whether or not the expander is expanded by default

Reveal text pattern

Param Description Required
triggerId Unique id of the trigger, must match content's one
contentId Unique id of the trigger, must match trigger's one
contentContent The content of the contents

The expander uses css to determine a collapsed state. If you apply a min-height attribute to the aui-expander-content element it will collapse to this height. If no min-height is specified the collapsed state is completely hidden.

An element containing the short version of the content to be shown when the content is hidden, must be placed as the child of a trigger.

.aui-expander-short-content deprecated

An element containing the short version of the content to be shown when the content is hidden, must be placed as the child of a trigger.

The AUI Expander throws the following events, you can hook into these events to add your own functionality to the expander:

Event Element Description
aui-expander-expanded aui-expander-trigger Triggers when the content is expanded.
aui-expander-collapsed aui-expander-trigger Triggers when the content is hidden/partially hidden.

You can also trigger the following events to manipulate the expander:

Event Element Description
aui-expander-invoke aui-expander-trigger invokes the trigger (collapses or expands it depending on the current state of content)
aui-expander-expand aui-expander-trigger expands the content
aui-expander-collapse aui-expander-trigger collapses the content

A11Y guidelines

Side note: whether you'd follow these guidelines or not, it's always advised to at least test your markup with a screen reader software.

Accessible trigger

Use button tag for the Expander trigger. If there is a special case to change this default tag, ensure that it remains operable with a keyboard and accessible for screen-reader users.

  • add role="button". This attribute indicates to assistive technologies that the element should be treated like a button.
  • set tabindex="0" on the tag. This makes the element focusable and allows it to be navigated to via the keyboard.

Remember!

The tabindex="0" attribute allows the custom button to be focused using the Tab key. It's important to note that you must implement functionality for the Enter and Space keys in your JavaScript.

HTML

Soy

These modifications can be made using the extraAttributes parameter in the Soy template.

Descriptive links

Non-descriptive and repetitive link texts, such as 'Read more', may lead to confusion for screen reader users.

There are two solutions:

  • Substitute 'Read more' with context-specific phrases, like 'Discover more about Earth's surface'.
  • Use the aria-label attribute to assign unique and descriptive text to each button.

Recommendation

Please use the Web Accessibility Initiative (WAI) patterns as a reference for implementing accessible components.