Accessible and lightweight Javascript components





GitHub Stars



Last Commit

13d ago








Type Definitions





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.


<button>Popup VanillaJS</button>
<core-toggle class="my-dropdown" popup hidden>
      <button>Can also be nested</button>
      <core-toggle class="my-dropdown" popup hidden>
          <li><input type="text" autofocus aria-label="Skriv her"></li>
<div id="jsx-toggle-popup"></div>
<script type="text/jsx">
    <button>Popup JSX</button>
    <CoreToggle className='my-dropdown' hidden popup onToggleSelect={console.warn}>
        <li><a href='#'>Link</a></li>
          <button>Can also be nested</button>
          <CoreToggle className='my-dropdown' hidden popup>
              <li><a href='#'>Sub-link</a></li>
  </>, document.getElementById('jsx-toggle-popup'))


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:

<script src="https://static.nrk.no/core-components/major/7/core-toggle/core-toggle.min.js"></script>  <!-- Using static -->

Remember to polyfill custom elements if needed.


HTML / JavaScript

<button>Toggle VanillaJS</button>       <!-- Must be <button> placed directly before <core-toggle> or use id + data-for attributes -->
  hidden                                <!-- Set hidden attribute to prevent FOUC -->
  popup="{Boolean|String}">             <!-- Optional. Defaults to false. Enable or disable if clicking outside toggle should close it. Provide a string to control the aria-label text on the toggle -->
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 popup value
myToggle.hidden         // Get hidden value
myToggle.value          // Get toggle button text

// Setters
myToggle.popup = true   // Enable or disable if clicking outside toggle should close it. Provide a string to control the aria-label text on the toggle
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'

  hidden                         // Set hidden attribute to prevent FOUC
  popup={Boolean|String}         // Optional. Defaults to false. Enable or disable if clicking outside toggle should close it. Provide a string to control the aria-label text on the toggle
  ref={(comp) => {}}             // Optional. Get reference to React component
  forwardRef={(el) => {}}        // Optional. Get reference to underlying DOM custom element
  onToggle={Function}            // Optional. Toggle event listener. See event 'toggle'
  onToggleSelect={Function}>     // Optional. Toggle select event listener. See event 'toggle.select'
  <button>Use with JSX</button>  // First element must result in a <button>. Accepts both elements and components
  <div>Content</div>             // Next element will be toggled. Accepts both elements and components


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 <core-toggle> 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:

  <button data-for="my-toggle">Toggle</button>
<core-toggle id="my-toggle" hidden>...</core-toggle>

Using the 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>:

  <svg style="width:1.5em; height:1.5em" aria-hidden="true"><use xlink:href="#nrk-heart"></use></svg>
<core-toggle popup="..." hidden>...</core-toggle>


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


When using core-toggle near the screen edges, the autoposition attribute positions the toggled content where there is visual room around the button, using position:fixed. This enables core-toggle to be used inside scrollable areas.

<div style="overflow:auto; height:70px; width:200px; border:2px dashed #ccc;">
  <button type="button">Toggle is autopositioned</button>
  <core-toggle class="my-dropdown" autoposition hidden>
      <li><a>Another link</a></li>
      <li><a>Linking is life</a></li>
  <p>Scroll me to the edge!</p>



Fired after open state changes:

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


Fired whenever an <a> or <button> element is selected inside a toggle with the 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


Note: <core-toggle> 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> and <core-toggle> 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>Toggle VanillaJS</button>  <!-- must be <button> -->
<core-toggle hidden>Content</core-toggle>  <!-- hidden prevents flash of unstyled content -->
<div id="jsx-toggle-default"></div>
<script type="text/jsx">
    <button>Toggle JSX</button>
    <CoreToggle hidden onToggle={console.log}>Content</CoreToggle>
  </>, document.getElementById('jsx-toggle-default'))

Example: Select

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>:

<button>Episode 1</button>
<core-toggle class="my-select my-dropdown" hidden popup="Choose episode">
    <li><button>Episode 1</button></li>
    <li><button>Episode 2</button></li>
    <li><button>Episode 3</button></li>
  document.addEventListener('toggle.select', (event) => {
    if (!event.target.classList.contains('my-select')) return
    event.target.value = event.detail
    event.target.hidden = true
<div id="jsx-toggle-select"></div>
<script type="text/jsx">
  class MyToggleSelect extends React.Component {
    constructor (props) {
      this.state = { value: 'Select number' }
      this.onSelect = this.onSelect.bind(this)
    onSelect (event) {
      event.target.hidden = true
      this.setState({ value: event.detail.textContent })
    render () {
      return <>
        <CoreToggle className='my-dropdown' popup='Example picker' hidden onToggleSelect={this.onSelect}>
  ReactDOM.render(<MyToggleSelect/>, document.getElementById('jsx-toggle-select'))


Why not use <details> instead?

Despite having a native <details> element for expanding/collapsing content, there are several issues regarding browser support, styling, accessibility. Furthermore, polyfills often conflict with other standards such as <dialog>.

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, <core-toggle> 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.

Rate & Review

Great Documentation0
Easy to Use0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Unwelcoming Community0
No reviews found
Be the first to rate


No alternatives found


No tutorials found
Add a tutorial