Jolty home Jolty Documentation

Collapse

An interactive component which opens and closes content via expandable panel.
<button data-ui-toggle="my-collapse" class="btn btn--md btn--primary btn--toggler mx-auto mb-2">
  Toggle content
  <svg
    xmlns="http://www.w3.org/2000/svg"
    width="24"
    height="24"
    viewBox="0 0 24 24"
    stroke-width="2.5"
    stroke="currentColor"
  >
    <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 8.25l-7.5 7.5-7.5-7.5"></path>
  </svg>
</button>
<div data-ui-collapse data-ui-transition-name="collapse" id="my-collapse" hidden>
  <div class="collapse-content">
    Some content that is hidden until you click on the button. It opens and closes with animation.
  </div>
</div>

Getting started

To start, create a <div> with a data-ui-collapse attribute, and a <button> with the data-ui-toggle attribute, specifying the div’s id.

html
<button data-ui-toggle="my-collapse">Toggle</button>
<div data-ui-collapse id="my-collapse" hidden>...</div>

Then, initialize all elements with the data-ui-collapse attribute.

js
import { Collapse } from "jolty";
Collapse.initAll();

Also, let’s toggle the arrow’s state using the CSS class .ui-active.

css
.my-toggler.ui-active span {
  scale: 1 -1;
}

Animation

To animate the collapse, you can use special CSS classes added during the entering and leaving state.

Since we are animating the height of the element, it is important to ensure that the collapse has overflow: hidden; property and doesn’t have padding.

If we want to use padding, then this element needs to be placed inside collapse.

html
<div data-ui-collapse class="collapsible-panel" hidden>
  <div class="collapsible-panel-inner">...</div>
</div>
css
.collapsible-panel-inner {
  padding: 1rem 1.5rem;
}

Also, if you want to make a gap between toggler and collapse, then an element or ::before pseudo-element should be added inside collapse.

css
.collapsible-panel::before {
  content: "";
  display: block;
  height: 0.5rem;
}

Animation can be created in many ways, here are just a few examples:

<div data-ui-collapse class="collapsible-panel" hidden>...</div>
 
<style>
  .collapsible-panel.ui-enter-active,
  .collapsible-panel.ui-leave-active {
    transition-duration: 200ms;
    transition-property: height, opacity;
    transition-timing-function: ease-in-out;
    overflow: hidden;
  }
  .collapsible-panel.ui-enter-to,
  .collapsible-panel.ui-leave-from {
    height: var(--ui-transition-height);
  }
  .collapsible-panel.ui-enter-from,
  .collapsible-panel.ui-leave-to {
    opacity: 0;
    height: 0;
  }
</style>

Data

If you don’t want to manually create unique ids, but generate them, you can use the Collapse.data() static method to set your own options for the component.

html
<button>Click me</button>
<div data-ui-collapse="my-collapse" hidden>...</div>
js
Collapse.data("my-collapse", (elem) => {
  return { toggler: elem.previousElementSibling };
});
 
Collapse.initAll();

You can also create a new instance of a class Collapse by passing a CSS selector or HTML element.

html
<button>Toggle</button>
<div id="my-collapse" hidden>...</div>
js
new Collapse("#my-collapse", (elem) => {
  return { toggler: elem.previousElementSibling };
});

If you want the component to change options or initialize/destroy at a certain screen size, you can use the breakpoints option.

js
new Collapse("#my-collapse", {
  destroy: true,
  transition: "collapse",
  breakpoints: {
    768: {
      destroy: false,
    },
  },
});

Dismissing

The Collapse component supports the data-ui-dismiss attribute, which is common for almost all components and data-ui-dismiss="collapse", which only closes collapse. In this example, we use data-ui-autodestroy because after closing it, we want to remove the element from the DOM and from the JS memory.

<div data-ui-collapse data-ui-autodestroy role="alert" class="alert">
  <div>
    <strong>Hi there!</strong> I just want to say that you are wonderful and to have a nice day.
  </div>
  <button data-ui-dismiss="collapse" aria-label="Close" type="button" class="btn btn--close">
    <svg
      xmlns="http://www.w3.org/2000/svg"
      fill="none"
      viewBox="0 0 24 24"
      width="24"
      height="24"
      stroke-width="2"
      stroke="currentColor"
    >
      <path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12"></path>
    </svg>
  </button>
</div>

Options

NameTypeDefaultDescription
initBooleantrueShould the instance be automatically initialized when an instance is created? If false, you’ll need to manually initiate it by calling collapse.init().
destroyBooleanfalseAllows you to destroy an instance at a specific breakpoint.
dataString''Allows you to use the default options that have been added through the Collapse.data() static method. Attribute: data-ui-collapse
onObjectnullUsed to register event handlers.
appearBooleannullIf you want to apply a transition upon initialization as well, you can set this option to true. Attribute: data-ui-appear
eventPrefixString'ui-collapse:'Prefix for events dispatched on the collapse element.
eventDispatchBoolean, EventName[]trueDefines if events are dispatched or used only within options.
eventBubbleBoolean, EventName[]trueDefines if events should bubble up the DOM.
breakpointsObjectnullDefines custom options for specific breakpoints.
shownBooleannullDefines if the collapse is expanded after initialization. By default, it’s null, which means it checks the hidden attribute or another attribute, depending on hideMode.
togglerCSSSelector, Element, Element[], Function({id}) => '[data-ui-toggle~="id"],[href="#id"]'Defines the toggler element.
togglerClassActiveString'ui-active'CSS class for toggler element when the collapse element is expanded.
collapseClassActiveString'ui-active'CSS class for the collapse element when it’s expanded.
awaitAnimationBooleanfalseCan the collapse state be switched if it’s in the process of animation?
hashNavigationBooleantrueDefines whether to open the collapse during initialization if the URL hash and the it’s id are the same. Attribute: data-ui-hash-navigation
dismissBoolean, CSSSelectortrueAllows the collapse to be closed when the button is clicked. By default, it’s true, meaning the hide() method will be called when the button with the '[data-ui-dismiss=""],[data-ui-dismiss="collapse"]' attribute is clicked.
autodestroyBooleanfalseDefines whether the instance should be destroyed after closing. Attribute: data-ui-autodestroy
a11yBooleantrueAdds aria-controls, aria-expanded and role="button" attributes to the toggler element.
hideModeString'hidden'Accepts one of the next values 'hidden','hidden-until-found','inert','class-hidden','class-shown','remove' Attribute: data-ui-hide-mode
keepPlaceBooleantrueDetermines if the component’s space is preserved when removed by hideMode: 'remove'.

Hide mode

The collapse can be hidden in several ways using the hideMode option.

ModeHidden stateDescription
'hidden'[hidden]Default mode, hides through display: none;
'hidden-until-found'[hidden="until-found"]The element will show when a match is found in the site search. Read more
'inert'[inert]Makes the element non-interactive, but remains visible
'class-hidden'.ui-hiddenThe element remains fully interactive,
adds the .ui-hidden class when hidden
'class-shown'-The element remains fully interactive,
adds the .ui-shown class when shown
'remove'-The element is removed from the DOM.
Add the hidden attribute to hide by default

Transition

AttributeTypeDefaultDescription
transitionString, Boolean, TransitionOptionstrueObject with transition options or string to set the name option for the transition.
nameString'ui'Defines the name of the transition that will be used to apply CSS rules. Attribute: data-ui-transition-name
cssBooleantrueDefines if the transition should be applied using CSS rules.
cssVariablesBooleantrueAdds special CSS variables during the transition to the collapse element and removes them after completion.
enterFunctionnullAccepts a function enter(el, done){}. call the done() callback to indicate transition end
enterActiveString, Object''CSS classes or styles applied during the entire entering phase. Attribute: data-ui-enter-active
enterFromString, Object''CSS classes or styles applied at the start of the entering phase. Attribute: data-ui-enter-from
enterToString, Object''CSS classes or styles applied at the end of the entering phase. Attribute: data-ui-enter-to
leaveFunctionnullAccepts a function leave(el, done){}. call the done() callback to indicate transition end
leaveActiveString, Object''CSS classes or styles applied during the entire leaving phase. Attribute: data-ui-leave-active
leaveFromString, Object''CSS classes or styles applied at the start of the leaving phase. Attribute: data-ui-leave-from
leaveToString, Object''CSS classes or styles applied at the end of the leaving phase. Attribute: data-ui-leave-to
durationNumbernullDefines the duration of the transition. Should be used only when the animation occurs on child elements.

If the cssVariables option is enabled, special CSS variables are added during the transition to collapse and are removed after its completion.

NameTypeDescription
--ui-transition-widthNumberThe width of the collapse element at the start of the transition.
--ui-transition-heightNumberThe height of the collapse element at the start of the transition.

Teleport

AttributeTypeDefaultDescription
teleportCSSSelector, Element, TeleportOptionsnullObject with TeleportOptions or CSSSelector, Element to set the to option for the teleport. Attribute: data-ui-teleport
toCSSSelector, ElementnullDefines where to move the collapse element.
positionString'beforeend'Defines the position for the collapse element once it has been moved. Accepts one of the next values 'beforebegin','afterbegin','beforeend' or 'afterend'
keepPlaceBooleanfalseDefines if the collapse element keeps its original place after being destroyed.

Methods

NameReturnDescription
init()instanceInitializes the component.
destroy(destroyOptions)instance, nullDestroys the component and accepts an object as a option { remove: false, keepInstance: false, keepState: false }.
update(options)instanceAccepts options as an argument and updates the component.
toggle(toggleOptions, force)promiseToggles the component’s visibility state between shown and hidden. Accepts true or false as a option, which sets the animated option or an object { animated: true, silent: false }.
show(toggleOptions)promiseOpens the component and accepts the same options as the toggle() method.
hide(toggleOptions)promiseCloses the component and accepts the same options as the toggle() method.

Class methods

NameReturnDescription
toggle(id, force, toggleOptions)promiseSearches for an instance by id and calls its toggle() method with the specified options.
show(id, toggleOptions)promiseSearches for an instance by id and calls its show() method with the specified options.
hide(id, toggleOptions)promiseSearches for an instance by id and calls its hide() method with the specified options.
data(name?, data)ClassSets default options for components that have the property data:'name' or through the attribute data-ui-collapse="name".
updateDefault(options)optionsUpdates default options.
initAll(root)instance[]Searches for elements in root, which defaults to document with the attribute data-ui-collapse and initializes them.
get(id or elem)instanceSearches for an instance by id or element (checks the base property).
getOrCreate(id or elem, options)instanceSearches for an instance by id or element (checks the base property), if not found, creates a new instance with specified options.

Properties

NameTypeDescription
idStringThe id of the base / collapse element.
isInitBooleanIndicates whether the instance is already initialized.
optsObjectContains the currently applied options for the current breakpoint.
baseOptsObjectContains all options, including the breakpoints option.
base, collapseElementAll components have a base property, which refers to the element through which the component is initialized and where events are fired. collapse is the same as base.
isOpenBooleanIndicates whether the collapse is currently shown.
initialPlaceNodeNodeReference to the node that is located where the collapse element was at the moment of initialization.

Class properties

NameTypeDescription
DefaultObjectContains the default options for all instances.
instancesMapA Map that contains all instances of the Collapse class.

Events

By default, events that are listened to directly through an element have the prefix 'ui-collapse:'. This can be changed through the eventPrefix option. Additionally, you can disable the bubbling of these events using the eventBubble option or turn them off entirely via the eventDispatch option.

Collapse.data("my-collapse", {
  on: {
    shown(instance, { trigger, event }) {
      // do something...
    },
    any(eventName, instance, { trigger, event }) {
      if (eventName === "shown") {
        // do something...
      }
    },
  },
});
 
// or directly on the collapse element
const collapseElem = document.querySelector(".my-collapse");
collapseElem.addEventListener("ui-collapse:show", (e) => {
  const [instance, { trigger, event }] = e.detail;
  // do something...
});
 
// or on the document
document.addEventListener("ui-collapse:show", (e) => {
  const [instance, { trigger, event }] = e.detail;
  // do something...
});
NameArgumentsDescription
beforeInitinstanceEvent will fired right before initialization.
initinstanceFires when initialization has been completed.
beforeShowinstance, {trigger, event}Fires immediately when the show() method is called.
showinstance, {trigger, event}Fires when the element becomes visible, but the CSS transition hasn’t started yet.
showninstance, {trigger, event}Fires when the CSS transition hasn’t been completed.
beforeHideinstance, {trigger, event}Fires immediately when the hide() method is called.
hideinstance, {trigger, event}Fires just before the CSS transition starts.
hiddeninstance, {trigger, event}Fires when the CSS transition has been completed.
beforeDestroyinstanceFires before the instance is destroyed.
destroyinstanceFires immediately when the destroy() method is called.
breakpointinstance, breakpoint, prevBreakpointFires when the breakpoint has been changed.
anyeventName, instanceFires on any event occurrence. The first argument contains the name of the event.
2023 © A Project by Jolty Labs 🇪🇸 🇺🇦