Repository files navigation

Lightweight and dependency-free content toggling with a focus on accessibility.

ctrly is a lightweight library which tries to solve 80% of the use-cases whereacontrol (usually a<button> element) toggles the visibility of atarget element.

It can be used to implement dropdown or off-canvas menus, modals, accordionsand similar UI elements. Example implementations can be found in theexamples/ directory.

Demos:Accordion •Dropdown •Offcanvas

Minified and gzipped, the total footprint weights about 3kB.

The recommended way to install ctrly is vianpm.

npm install ctrly

After installation,ctrly can be imported as a module.

importctrlyfrom'ctrly';

The latest version can also be downloaded or included fromunpkg orjsDelivr.

<scriptsrc="/path/to/ctrly.js"></script>

Thectrly() function is then globally available.

A typical setup includes acontrol (usually a<button> element) whichtoggles the visibility of atarget element.

The control must have adata-ctrly attribute which must contain the ID of thetarget.

<buttondata-ctrly="my-target">Toggle</button><sectionid="my-target">You clicked the toggle to make me visible</section>

To initialize all controls, thectrly() function must be called once.

ctrly();

ctrly then adds all required ARIA attributes:

• Thearia-controls andaria-expanded attributes to the control.
• Thearia-hidden andaria-labelledby to the target.

If the control does not have anid attribute, ctrly will add an auto-generatedID.

The fully generated HTML looks like the following.

<buttondata-ctrly="my-target"id="ctrly-control-1"aria-controls="my-target"aria-expanded="false">    Toggle</button><sectionid="my-target"aria-hidden="false"aria-labelledby="ctrly-control-1">    You clicked the toggle to make me visible</section>

Note: ctrly does not ship with any default CSS which shows and hides thetarget element as it makes no assumptions on how the visibility is controlled.

This must be implemented depending on thearia-hidden attribute which istoggled to eitherfalse ortrue by ctrly.

/* Toggle via the display property */.target-selector[aria-hidden="true"] {display: none;}/* Toggle via the visibility property */.target-selector[aria-hidden="true"] {visibility: hidden;}

It is also good practice to hide the controls if JavaScript is disabled.

This can be done depending on the presence of thearia-controls attributeadded by ctrly.

.control-selector:not([aria-controls]) {display: none;}

While it is highly recommended to use<button> elements as controls, ctrlyalso supports other HTML elements.

<spandata-ctrly="my-target">Toggle</button>

The fully generated HTML looks like the following (note the additionaltabindex,role andaria-pressed attributes).

<spandata-ctrly="my-target"id="ctrly-control-1"aria-controls="my-target"aria-expanded="false"tabindex="0"role="button"aria-pressed="false">    Toggle</span>

The return value of thectrly() function is an object with the followingfunctions.

• closeAll
• destroy
• init

This function closes all open targets.

const{ closeAll}=ctrly();closeAll();

This function reverts all elements to their initial state and unbinds all eventlisteners.

const{ destroy}=ctrly();destroy();

This function (re)initializes all controls. This can be useful after the DOMhas been updated, eg. controls have been added dynamically.

const{ init}=ctrly();init();

ctrly's behavior can be controlled by passing an options object as the firstargument.

ctrly({// Options...});

The following options are available.

• selector
• context
• focusTarget
• closeOnBlur
• closeOnEsc
• closeOnOutsideClick
• closeOnScroll
• trapFocus
• allowMultiple
• on
• autoInit

Default:[data-ctrly]

A selector for the control elements.

<buttonclass="my-control"data-ctrly="my-target">Toggle</button>

ctrly({selector:'.my-control'});

Default:null

A selector to group targets together. Can be used in combination with theallowMultiple option to allow or disallow multiple opentargets inside a context.

See theaccordion example for a use-case.

<divclass="my-context"><buttondata-ctrly="my-target">Toggle</button></div><divclass="my-context"><buttondata-ctrly="my-target">Toggle</button></div>

ctrly({context:'.my-context'});

Default:true

By default, once the target becomes visible, the focus is shifted to the firstfocusable element inside the target. Passingfalse as an option disables thisbehavior.

ctrly({focusTarget:false});

Default:true

By default, targets are closed when the focus is shifted from an element insidethe target to an element outside the target. Passingfalse as an optiondisables this behavior.

This setting is alwaysfalse iftrapFocus is settotrue.

ctrly({closeOnBlur:false});

Default:true

By default, targets are closed when theESC key is pressed. Passingfalse as an option disables this behavior.

ctrly({closeOnEsc:false});

Default:true

By default, targets are closed when there is a mouse click outside the target.Passingfalse as an option disables this behavior.

ctrly({closeOnOutsideClick:false});

Default:false

Passingtrue as an option closes a target when the window is scrolled andthe mouse is currently not inside the target element.

ctrly({closeOnScroll:true});

Default:false

Passingtrue as an option ensures thatTAB andSHIFT+TAB do not move focus outside the target.

ctrly({trapFocus:true});

Default:false

By default, if a target becomes visible, all other open targets are closed.Passingtrue as an option allows multiple targets to be opened at the sametime.

This can be combined with thecontext option to only allow multipleopen targets inside a context element.See theaccordion example for a use-case.

To allow multiple open targets,closeOnBlur must be set tofalse.

ctrly({allowMultiple:true});

Default:{}

Allows to define event callbacks as{event: callback} pairs.

ctrly({on:{open:target=>{// Called before a target is opened},opened:target=>{// Called after a target has been opened},close:target=>{// Called before a target is closed},closed:target=>{// Called after a target has been closed}}});

More information about the event callbacks can be found in theEvents section.

Default:true

By default, initialization is done when callingctrly(). Passingfalse asan option disables this behavior and theinit() method must be calledmanually.

const{ init}=ctrly({autoInit:false});init();

ctrly triggers several events when a target is opened or closed.

There are 2 ways to bind listeners to the events.

1. Through theon option.
2. Through DOM event listeners on the target element (the DOM event names areprefixed withctrly:, eg.ctrly:open).

The following events are available.

• open
• opened
• close
• closed

Triggered before the target element is opened.

ctrly({on:{open:target=>{target.classList.add('is-opening');}}});// ordocument.getElementById('my-target').addEventListener('ctrly:open',e=>{consttarget=e.target;target.classList.add('is-opening');});

Triggered after the target element has been opened.

ctrly({on:{opened:target=>{target.classList.remove('is-opening');}}});// ordocument.getElementById('my-target').addEventListener('ctrly:opened',e=>{consttarget=e.target;target.classList.remove('is-opening');});

Triggered before the target element is closed.

ctrly({on:{close:target=>{target.classList.add('is-closing');}}});// ordocument.getElementById('my-target').addEventListener('ctrly:close',e=>{consttarget=e.target;target.classList.add('is-closing');});

Triggered after the target element has been opened.

ctrly({on:{closed:target=>{target.classList.remove('is-closing');}}});// ordocument.getElementById('my-target').addEventListener('ctrly:closed',e=>{consttarget=e.target;target.classList.remove('is-closing');});

• BrowserStack for providing free VMs for automated testing.
• GitHub for providing free Git repository hosting.
• npm for providing the package manager for JavaScript.
• TravisCI for providing a free build server.

Copyright (c) 2018-2021 Jan Sorgalla.Released under theMIT license.