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.
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-selectordeprecated
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-expandeddeprecated
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
replaceSelectordeprecated
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.