README

o-toggle

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

Usage
Markup
Sass
JavaScript
Migration guide
Contact
Licence

Usage

Check out how to include Origami components in your project to get started with o-toggle.

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));

@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 '@financial-times/o-toggle';
document.addEventListener("DOMContentLoaded", function() {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

Or by calling the init method:

import Toggle from '@financial-times/o-toggle';
Toggle.init();

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

import Toggle from '@financial-times/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:

target: HTMLElement or selector of the element that will be toggled
callback: Function or content of a function as string that will be executed every time a toggle happens. It has the following parameters:
- State. 'open' or 'close'
- Click event object if it comes from the event handler on the toggle

Migration guide

State	Major Version	Last Minor Release	Migration guide
✨ active	3	N/A	migrate to v3
⚠ maintained	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.

Usage no npm install needed!