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 where
a control (usually a <button> element) toggles the visibility of a
target element.
It can be used to implement dropdown or off-canvas menus, modals, accordions
and similar UI elements. Example implementations can be found in the
examples/ directory.
Minified and gzipped, the total footprint weights about 2.7kB.
The recommended way to install ctrly is via npm.
npm install ctrly
After installation, ctrly can be imported as a module.
import ctrly from 'ctrly';
The latest version can also be downloaded or included from unpkg or jsDelivr.
<script src="/path/to/ctrly.js"></script>
The ctrly() function is then globally available.
A typical setup includes a control (usually a <button> element) which
toggles the visibility of a target element.
The control must have a data-ctrly which must contain the ID of the target.
<button data-ctrly="my-target">Toggle</button>
<section id="my-target">You clicked the toggle to make me visible</section>
The specification also allows a ID reference list (a list of multiple, space-separated ID references) as value of the
arial-controlsattribute. This is not supported by ctrly and only a single ID reference is allowed.
To initialize all controls, the ctrly() function must be called once.
ctrly();
ctrly then adds all required ARIA attributes, the aria-controls and
aria-expanded attributes to the control and the aria-hidden and
aria-labelledby to the target.
If the control does not have an id attribute, ctrly will add an auto-generated
ID.
The fully generated HTML looks like the following.
<button
data-ctrly="my-target"
id="ctrly-control-1"
aria-controls="my-target"
aria-expanded="false">
Toggle
</button>
<section
id="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 the target element as it makes no assumptions on how the visibility is controlled.
This must be implemented depending on the aria-hidden attribute which is
toggled to either false or true 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 the aria-controls attribute
added by ctrly.
.control-selector:not([aria-controls]) {
display: none;
}
The return value of the ctrly() function is an object with the following
functions.
This function closes all open targets and unbinds all event listeners.
const { destroy } = ctrly();
destroy();
This function (re)initializes all controls. This can be useful after the DOM has 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 first argument.
ctrly({
// Options...
});
The following options are available.
Default: [data-ctrly]
A selector for the control elements.
<button class="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 the allowMultiple option to allow or disallow multiple open targets inside a context.
See the accordion example for a use-case.
<div class="my-context">
<button data-ctrly="my-target">Toggle</button>
</div>
<div class="my-context">
<button data-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 first
focusable element inside the target. Passing false as an option disables this
behavior.
ctrly({
closeOnScroll: false
});
Default: true
By default, targets are closed when the focus is shifted from an element inside
the target to an element outside the target. Passing false as an option
disables this behavior.
This setting is always
falseiftrapFocusis set totrue.
ctrly({
closeOnBlur: false
});
Default: true
By default, targets are closed when the ESC key is pressed. Passing
false 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.
Passing false as an option disables this behavior.
ctrly({
closeOnOutsideClick: false
});
Default: false
Passing true as an option closes a target when the window is scrolled and
the mouse is currently not inside the target element.
ctrly({
closeOnScroll: true
});
Default: false
Passing true as an option ensures that TAB and
SHIFT+TAB do not move focus outside the target.
ctrly({
closeOnScroll: false
});
Default: false
By default, if a target becomes visible, all other open targets are closed.
Passing true as an option allows multiple targets to be opened at the same
time.
This can be combined with the context option to only allow multiple open targets inside a context element. See the accordion example for a use-case.
To allow multiple open targets,
closeOnBlurmust 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
}
}
});
Default: true
By default, initialization is done when calling ctrly(). Passing false as
an option disables this behavior and the init() method must be called
manually.
const { init } = ctrly({
autoInit: false
});
init();
More information about the event callbacks can be found in the Events section.
ctrly triggers several events when a target is opened or closed.
There are 2 ways to bind listeners to the events.
on option.ctrly: eg. ctrly:open).The following events are available.
Triggered before the target element is opened.
ctrly({
on: {
open: target => {
target.classList.add('is-opening');
}
}
});
// or
document.getElementById('my-target').addEventListener('ctrly:open', e => {
const target = e.target;
target.classList.add('is-opening');
});
Triggered after the target element has been opened.
ctrly({
on: {
opened: target => {
target.classList.remove('is-opening');
}
}
});
// or
document.getElementById('my-target').addEventListener('ctrly:opened', e => {
const target = e.target;
target.classList.remove('is-opening');
});
Triggered before the target element is closed.
ctrly({
on: {
close: target => {
target.classList.add('is-closing');
}
}
});
// or
document.getElementById('my-target').addEventListener('ctrly:close', e => {
const target = e.target;
target.classList.add('is-closing');
});
Triggered after the target element has been opened.
ctrly({
on: {
closed: target => {
target.classList.remove('is-closing');
}
}
});
// or
document.getElementById('my-target').addEventListener('ctrly:closed', e => {
const target = e.target;
target.classList.remove('is-closing');
});
Copyright (c) 2018 Jan Sorgalla. Released under the MIT license.
FAQs
Lightweight and dependency-free content toggling with a focus on accessibility.
The npm package ctrly receives a total of 48 weekly downloads. As such, ctrly popularity was classified as not popular.
We found that ctrly demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.