Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/scottaohara/aria_disclosure_widget

Progressively enhanced hide/show content areas with vanilla JS & appropriate ARIA attributes
https://github.com/scottaohara/aria_disclosure_widget

accessibility aria details-summary-alternative disclosure-widget toggle-buttons

Last synced: about 1 month ago
JSON representation

Progressively enhanced hide/show content areas with vanilla JS & appropriate ARIA attributes

Awesome Lists containing this project

README 

        
# ARIA Disclosure Widgets  



A disclosure widget consists of a trigger (``) that toggles the hidden state of its associated content.  



Check out the [demo page](https://scottaohara.github.io/aria_disclosure_widget/) for markup patterns and variations.



## How does it work?  



Use either a `` (for `display: inline-block`) or `` (for `display: block`) custom element wrapping element.



Whichever wrapping element used, it MUST contain a `` element. This element represents the content you want to show/hide. 



The minimal expected markup pattern for this script to work is as follows:

```html

 

  

    ...

  



```



### The trigger



A `` element to toggle the `` will be auto generated by the script. Use the `data-trigger` attribute on the `` or `` element to provide this element a visible label and its accessible name.  If the `data-trigger` attribute is not specified, the generated `` will render a fallback label of "More info".



```html



  

    ...

  



```



If you want more control over the placement of the generated `` element, and thus also include additional structured and semantic content to your disclosure widget, then you can use the `data-insert-trigger` to specify the element where the `` will be generated.  The content of the chosen element will become the content of the `` element.



```html



  


    

    Visible text label

  


  

    ...

  



```



Per the above markup, the `` will be insterted into the `
` element.  The resulting markup will render as follows:

```html



  

    

    Visible text label

  



```



Alternatively, the `` can be injected into another element as an inline trigger. This will render the `` with only the down arrow/chevron icon, and use an `aria-label="More info"` to provide it an accessible name.  Consider the following markup:



```html



  


    My topic here

    

  


  ...



```



The resulting markup will render as follows:

```html



  My topic here

  

    

  



```



### Other options



The following attributes are available to use on the wrapping `` or `` element:

* `data-open` – Use to open a disclosure widget by default.

* `data-disabled` - Will add a `disabled` attribute to the generated ``.

* `data-left-align` - Will render the down arrow / chevron on the left of the ``, rather than the default right position.

* `data-popup` - The `` will be displayed as a faux "popup". If keyboard focus is detected outside of the widget, the popup content will auto-collapse and the `` will return to the `aria-expanded=false` state. When identified as a "popup", the content panel will be provided a `tabindex=-1` and a `role=note`. Comments describing why are provided in the JavaScript file.



## Keyboard controls



The `` element allows for default Space and Enter keys to toggle the expanded and collapsed state of the associated content.



If the disclosure widget is rendered as a popup, then the Esc key can be used to collapse the content if focus is on the `` element, or within the expanded disclosure widget content container.  Pressing Esc will return focus to the `` element of the disclosure widget.



## License & such  

This script was written by [Scott O'Hara](https://twitter.com/scottohara).



It has an [MIT license](https://github.com/scottaohara/accessible-components/blob/master/LICENSE.md).



Do with it what you will :)