@financial-times/o-toggle v3.2.6

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

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 '@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

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.