Core Toggle

> @nrk/core-toggle makes a <button> toggle the visibility of next element sibling. Toggles can be nested and easily extended with custom animations or behavior through the toggle event.

Example

</button><button type="button">Popup VanillaJS</button>

  <ul>
    <li><a>Link</a></li>
    <li>
      <button type="button">Can also be nested</button>
      
        <ul>
          <li><a>Sub-link</a></li>
          <li><input aria-label="Skriv her" type="text"></li>
        </ul>
      
    </li>
  </ul>

<div id="jsx-toggle-popup"></div>

Installation

Using NPM provides own element namespace and extensibility. Recommended:

npm install @nrk/core-toggle  # Using NPM

Using static registers the custom element with default name automatically:

Remember to polyfill custom elements if needed.

Usage

HTML / JavaScript

<button type="button">Toggle VanillaJS</button>       

  data-popup="{String?}"                
&gt;
  Content                               

import CoreToggle from '@nrk/core-toggle'                 // Using NPM
window.customElements.define('core-toggle', CoreToggle)   // Using NPM. Replace 'core-toggle' with 'my-toggle' to namespace

const myToggle = document.querySelector('core-toggle')

// Getters
myToggle.button         // Get toggle button element
myToggle.popup          // Get data-popup value
myToggle.hidden         // Get hidden value
myToggle.value          // Get toggle button text

// Setters
myToggle.popup = {Boolean|String}   // If true, clicking outside open toggle will close it. Providing a string also enables select-behavior, by replacing value inside button with selected value, and suffixes provided string to aria-label on button
myToggle.hidden = true              // Set hidden attribute
myToggle.value = 'Velg'             // Sets innerHTML of the button and safely updates aria-label for screen readers. Defaults to button.innerHTML

React / Preact

import CoreToggle from '@nrk/core-toggle/jsx'

<button type="button">Use with JSX</button>
 {}}             // Optional. Get reference to React component
  forwardRef={(el) =&gt; {}}        // Optional. Get reference to underlying DOM custom element
  value={String}                 // Optional. Set selected value in order to get correct aria-label. See "Example: Select"
  onToggle={Function}            // Optional. Toggle event listener. See event 'toggle'
  onToggleSelect={Function}      // Optional. Toggle select event listener. See event 'toggle.select'
&gt;
  Content                        // Content to be toggled. Accepts text, elements and components

Markup

With for

Putting the toggle button directly before the content is highly recommended, as this fulfills all accessibility requirements by default. There might be scenarios though, where styling makes this DOM structure impractical. In such cases, give the <button> a data-for attribute (for is deprecated), and the `` an id with corresponding value. Make sure there is no text between the button and toggle content, as this will break the experience for screen reader users:

<div>
  </div></button><button type="button" data-for="my-toggle">Toggle</button>

...

Popup and button HTML

Using the data-popup attribute in conjunction with embedded HTML in your toggle button (an SVG icon for instance) will only preserve text when updating the value/label for the button. To preserve the embedded HTML, put the actual button text inside a <span>:

<button type="button">
  <span>Toggle</span>
  <svg aria-hidden="true" style="width:1.5em; height:1.5em"></svg>
</button>
...

Autofocus

If you have form elements inside a ``, you can optionally add a autofocus attribute to the most prominent form element. This helps the user navigate quickly when toggle is opened.

Autoposition

When using core-toggle near the screen edges, the autoposition attribute positions the toggled content where there is visual room around the toggle, using position:fixed, relative to the screen edges. This can be useful when core-toggle is used inside narrow and/or scrollable areas.

<p>This example illustrates how core-toggle with <code style="font-size: 16px">autoposition</code> draws relative to the screen edge marked by the red frame</p>

Events

toggle

Fired after open state changes:

document.addEventListener('toggle', (event) => {
  event.target   // The toggle element
})

toggle.select

Fired whenever an <a> or <button> element is selected inside a toggle with the data-popup option enabled. Useful for setting the value of the toggle button with the selected value.

document.addEventListener('toggle.select', (event) => {
  event.target   // The toggle element
  event.detail   // The selected element
  event.target.value = event.detail  // Example: set value of toggle to selected element
})

Styling

Note: is `display: inline` by default. Change this by for instance setting `core-toggle:not([hidden]) { display: block | flex | grid }` or similar in your app. Not needed when `position` or `float` is used. All styling in documentation is example only. Both the `</button><button>` and element receive attributes reflecting the current toggle state:

.my-button {}                         /* Target button in any state */
.my-button[aria-expanded="true"] {}   /* Target only open button */
.my-button[aria-expanded="false"] {}  /* Target only closed button */

.my-toggle-content {}                 /* Target content in any state */
.my-toggle-content:not([hidden]) {}   /* Target only open content */
.my-toggle-content[hidden] {}         /* Target only closed content */

Example: Expand

Content is only toggled when clicking the button. Great for accordions and expand/collapse panels.

</button><button type="button">Toggle VanillaJS</button>  
Content  

<div id="jsx-toggle-default"></div>

Example: Select

data-popup-attribute is required for Select behavior

Listen to the toggle.select event and update the button's value from the selected item to create a component that behaves like a <select>:

HTML and JavaScript

Episode 1

  
    Episode 1
    Episode 2
    Episode 3
  

React class component

React function component

FAQ

Why not use `` instead?

Despite having a native [](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) element for expanding/collapsing content, there are several issues regarding [browser support](https://caniuse.com/#feat=details), [styling](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details#Example_with_styling), [accessibility](https://accessibleculture.org/articles/2012/03/screen-readers-and-details-summary/). Furthermore, polyfills often conflict with other standards such as .

Why is there no role="menu" in dropdowns?

The menu role is mainly inteded for context menues and toolbars in application interfaces, and has quite complex keyboard navigation requirements. As most end users will not expect application behavior in websites and internal web based systems, (implemented) attributes like aria-controls and aria-labelledby is sufficient for a good user experience.

Why does dropdowns not open on hover?

Both touch devices and screen readers will have trouble properly interacting with hoverable interfaces (unless more complex fallback logic is implemented). To achieve a consistent and accessible interface, `` is designed around click interactions.

Why is there no group-option to achieve a single open toggle?

Some expand/collapse interfaces like accordions behaves like a group - allowing only one expanded area at the time. This pattern however requires more logic and carefully designed animations to avoid confusion over expected scroll position.

Example: The user first opens "Toggle-1", and then "Toggle-2" (which closes "Toggle-1"). Since "Toggle-1" is placed above, the position "Toggle-2" now changes - potentially outside the viewport on smaller devices. Note: If you do need to implement grouping, you can achieve this by reacting to the toggle event.