Origami Frontend Components & Services

Readme: o-toggle

This utility component adds toggle (show/hide) behaviour to a <button> or <a> tag and a target.

Markup

Add the data-o-component="o-toggle" and data-o-toggle-target to your toggle element (e.g. <button>). Where the value of data-o-toggle-target is the CSS selector for the element you want to show/hide.

When the toggle is clicked a class o-toggle--active is toggled on the target as well as its aria-hidden attribute. Use these in your project to style the target according to if the toggle is on or off. Alternatively, add the class o-toggle-display (to totally hide the target) or o-toggle-visibility (to layout but visually hide the target) when the toggle is not active.

<button data-o-component="o-toggle" data-o-toggle-target="#my-target">My button</button>
<div id='my-target' class="o-toggle o-toggle-display">Some toggleable content</div>

The data attribute data-o-toggle-callback may also be set to the name of a function as a string that will be executed every time a toggle happens. E.g:

<script>
    window.myToggleCallback = function(state, event) {
        if (state === 'open') {
            console.log('Target opened');
        } else if (state === 'close') {
            console.log('Target closed');
        }
    };
</script>
<button data-o-component="o-toggle" data-o-toggle-target="#my-target" data-o-toggle-callback="myToggleCallback">My button</button>
<div id='my-target' class="o-toggle o-toggle-display">Some toggleable content</div>

Sass

Projects may choose to style active targets themselves using the o-toggle--active class or aria-hidden attribute. However to use the o-toggle helper classes o-toggle-display and o-toggle-visibility classes (see Markup call the mixin @include oToggle():

@include oToggle();

Alternatively the classes may be included granularly with an $opts map:

@include oToggle($opts: ('display': true));

or

@include oToggle($opts: ('visibility': true));

JavaScript

As with other Origami components, all o-toggle instances on the page with the data attribute data-o-component="o-toggle" may be constructed with the o.DOMContentLoaded event.

import 'o-toggle';
document.addEventListener("DOMContentLoaded", function() {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

Or by calling the init method:

import Toggle from 'o-toggle';
Toggle.init();

Toggles may also be constructed individually without data-o-component="o-toggle":

import Toggle from 'o-toggle';
const toggleEl = document.querySelector('.o-toggle');
const toggle = new Toggle(toggleEl, {
        target: '.my-target',
        callback: function(state, event) {
            if (state === 'open') {
                console.log('Target opened');
            } else if (state === 'close') {
                console.log('Target closed');
            }
        }
    });

A second parameter can be passed to the oToggle constructor or to the .init() function with a config object that has the following options:

Migration

State Major Version Last Minor Release Migration guide
✨ active 2 N/A migrate to v2
╳ deprecated 1 1.2 N/A

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.


Licence

This software is published by the Financial Times under the MIT licence.

Support Status
active
Switch component view

GitHub Repository

Install o-toggle

If using the Build Service, add o-toggle@^2.0.3 to your script and link tags.

If running a Manual Build, run bower install --save "o-toggle@^2.0.3".

Help & Support

o-toggle is maintained directly by the Origami team. If you have any questions about o-toggle or Origami in general, we are happy to help. 😊

Slack: #origami-support
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #origami-support
Email: origami.support@ft.com