Tablist

A universal component that allows creating accordions and tabs, without the need to specify unique ids, with accessibility support and keyboard navigation.

ARIA design pattern

Getting started

Let’s start by creating a simple accordion that, when clicking on a button, will open a new panel and close the previous one.

html

<div data-ui-tablist class="ui-accordion" data-ui-transition="collapse">
  <div class="ui-accordion-item">
    <button data-ui-tablist-tab class="ui-accordion-header ui-active">Accordion header #1</button>
    <div data-ui-tablist-tabpanel>
      <div class="ui-accordion-body">...</div>
    </div>
  </div>
  <div class="ui-accordion-item">
    <button data-ui-tablist-tab class="ui-accordion-header">Accordion header #2</button>
    <div data-ui-tablist-tabpanel hidden>
      <div class="ui-accordion-body">...</div>
    </div>
  </div>
</div>

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

import { Tablist } from "jolty";
Tablist.initAll();

If you want the tabpanel to open when the URL contains a hash with its id, you can assign it a unique id, and for tab set the data-ui-tablist-tab="{id}" attribute.

If we link tab with tabpanel through a unique id, specifying the data-ui-tablist-tabpanel attribute is unnecessary.

html

<div data-ui-tablist>
  <button data-ui-tablist-tab="my-tabpanel">Tab #1 <span>↓</span></button>
  <div id="my-tabpanel" hidden>Some content #1</div>
  ...
</div>

Tabs

html

<div class="ui-tabs" data-ui-tablist="ui-tabs">
  <button class="tab" data-ui-tablist-tab="log-in">Log in</button>
  <button class="tab" data-ui-tablist-tab="sign-up">Sign up</button>
</div>
<div id="log-in">...</div>
<div id="sign-up" hidden>...</div>

By default, Tablist has accordion settings; to change them to tabs, you need to add the value 'ui-tabs' to the data-ui-tablist attribute or set the data:'ui-tabs' option.

html

<div data-ui-tablist="ui-tabs">
  <button data-ui-tablist-tab="tabpanel-1">Tab #1</button>
  <button data-ui-tablist-tab="tabpanel-2">Tab #2</button>
  <button data-ui-tablist-tab="tabpanel-3">Tab #2</button>
</div>
<div id="tabpanel-1">Tabpanel with id:</div>
<div id="tabpanel-2" hidden>Tabpanel with id:</div>
<div id="tabpanel-3" hidden>Tabpanel with id:</div>

Tabpanel with id:

Below are two sets of settings; by default, Tablist has settings from the 'ui-accordion' list:

Defaults for the 'ui-tabs' value:

{
  alwaysExpanded: true,
  horizontal: true,
  arrowActivation: true,
  awaitPrevious: true,
  a11y: 'tabs'
}

Defaults for the 'ui-accordion' value:

{
  alwaysExpanded: false,
  horizontal: false,
  arrowActivation: false,
  awaitPrevious: false,
  a11y: 'accordion'
}

Settings groups

But what if we do not want to specify unique ids or want to use the same settings for other tablists? There is a solution for this - use the static method Tablist.data().

html

<div data-ui-tablist="tabs">
  <button data-ui-tablist-tab>Tab #1</button>
  <button data-ui-tablist-tab>Tab #2</button>
  <button data-ui-tablist-tab>Tab #3</button>
</div>
<div>
  <div>Tabpanel with id:</div>
  <div hidden>Tabpanel with id:</div>
  <div hidden>Tabpanel with id:</div>
</div>

Tablist.data("tabs", (tablistElem) => {
  return {
    data: "ui-tabs",
    tabpanel: tablistElem.nextElementSibling.children,
  };
});
Tablist.initAll();

We also use data: "ui-tabs" to import the default settings for tabs.

Tabpanel with id:

Styles

Accordion

.accordion {
  --ui-accordion-bg: transparent;
  --ui-accordion-gap: 0.375rem;
  --ui-accordion-header-bg: var(--gray-1);
  --ui-accordion-header-hover-bg: var(--gray-2);
  --ui-accordion-header-open-color: var(--gray-12);
  --ui-accordion-header-open-bg: var(--gray-1);
  --ui-accordion-header-open-bg-hover: var(--gray-2);
  --ui-accordion-header-padding: 0.75rem 0.75rem 0.75rem 1rem;
  --ui-accordion-header-font-size: var(--text-sm);
  --ui-accordion-header-font-weight: 500;
  --ui-accordion-outline: 2px solid var(--gray-11);
  --ui-accordion-outline-offset: -2px;
  --ui-accordion-arrow-size: 1.375rem;
  --ui-accordion-arrow-icon: var(--ui-icon-chevron-down);
  --ui-accordion-body-padding: 1rem;
  --ui-accordion-border-width: 0;
  --ui-accordion-border-style: var(--ui-border-style);
  --ui-accordion-border-color: var(--ui-border-color);
  --ui-accordion-border-radius: var(--radius);
}
.accordion--outlined {
  --ui-accordion-border-width: var(--ui-border-width);
}
.accordion--outlined :where(.accordion-item) {
  border-radius: var(--ui-accordion-border-radius);
}

Tabs

.tabs {
  --ui-tabs-bg: transparent;
  --ui-tabs-height: var(--ui-size-lg);
  --ui-tabs-border-width: 0;
  --ui-tabs-border-style: var(--ui-border-style);
  --ui-tabs-border-color: var(--ui-border-color);
  --ui-tabs-border-radius: var(--radius);
  --ui-tabs-padding: 0.25rem;
  --ui-tab-font-size: var(--text-sm);
  --ui-tab-font-weight: 500;
  --ui-tab-color: var(--gray-11);
  --ui-tab-hover-color: var(--gray-12);
  --ui-tab-current-color: var(--gray-12);
  --ui-tab-current-bg: var(--gray-a2);
  --ui-tab-padding: 0 1rem;
  --ui-tab-border-radius: calc(var(--radius) - 0.25rem);
}
.tabs--sm {
  --ui-tabs-height: var(--ui-size-md);
  --ui-tab-font-size: var(--text-xs);
  --ui-tab-padding: 0 0.75rem;
}
.tabs--outlined {
  --ui-tabs-bg: var(--ui-main-bg);
  --ui-tabs-border-width: var(--ui-border-width);
}
.tabs--no-radius {
  --ui-tabs-padding: 0;
  --ui-tabs-border-radius: 0;
  --ui-tab-border-radius: 0;
}

Options

Name	Type	Default	Description
`init`	`Boolean`	`true`	Should the instance be automatically initialized when an instance is created? If `false`, you’ll need to manually initiate it by calling `tablist.init()`.
`destroy`	`Boolean`	`false`	Allows you to destroy an instance at a specific breakpoint.
`data`	`String`	`''`	Allows you to use the default options that have been added by the `Tablist.data()` static method. Attribute: `data-ui-tablist`
`on`	`Object`	`null`	Used to register event handlers.
`appear`	`Boolean`	`null`	If you want to apply a transition upon initialization as well, you can set this option to `true`. Attribute: `data-ui-appear`
`eventPrefix`	`String`	`'ui-tablist:'`	Prefix for events dispatched on the `tablist` element.
`eventDispatch`	`Boolean, EventName[]`	`true`	Defines if events are dispatched or used only within options.
`eventBubble`	`Boolean, EventName[]`	`true`	Defines if events should bubble up the DOM.
`breakpoints`	`Object`	`null`	Defines custom options for specific breakpoints.
`shown`	`id, index, id[], index[], function`	`null`	Accepts id, index or an array of them, there is also an option to set function shown: `(Tab) => Boolean`.
`siblings`	`Boolean`	`true`	Should the `tab` element look for its `tabpanel` among the following elements?
`alwaysExpanded`	`Boolean`	`false`	Should at least one tab always be open? Attribute: `data-ui-always-expanded`
`multiExpand`	`Boolean`	`false`	Can more than one tab be opened at the same time? Attribute: `data-ui-multi-expand`
`awaitAnimation`	`Boolean`	`false`	Can the tab state be switched if the tablist is in the process of animation?
`awaitPrevious`	`Boolean`	`false`	Should the next tab wait for the previous animation to end?
`keyboard`	`Boolean`	`true`	Enables tabs field via arrow keys.
`arrowActivation`	`Boolean`	`false`	Should the tab be turned on as soon as it was focused?
`rtl`	`Boolean`	`false`	Creates inversion in switching tabs by the keyboard.
`focusFilter`	`Function`	`null`	Determines whether the `tab` element can be focused from the keyboard or not. Accepts a function: `(Tab) => Boolean`.
`horizontal`	`Boolean`	`false`	Determines in which direction the keyboard field is performed. Attribute: `data-ui-horizontal`
`tab`	`CSSSelector, Element[], Function`	`'[data-ui-tablist-tab]'`	Defines a selector for searching the `tab`, also accepts a list of tabs in an array or a function tab: `(Tablist) => Element[] or CSSSelector`.
`tabpanel`	`CSSSelector, Function, Element[]`	`'[data-ui-tablist-tabpanel]'`	Defines a selector for searching for `item` elemen among the parents of `tab`, also accepts a function tabpanel: `({tablist, tab, index}) => Element`.
`tabClassActive`	`String`	`'ui-active'`	CSS class for the `tab` element when it’s expanded.
`itemClassActive`	`String`	`'ui-active'`	CSS class for the `item` element when it’s expanded.
`tabpanelClassActive`	`String`	`'ui-active'`	CSS class for the `tabpanel` element when it’s expanded.
`hashNavigation`	`Boolean`	`true`	Defines whether to show the tab during initialization if the URL hash is equal to the id. Attribute: `data-ui-hash-navigation`
`dismiss`	`Boolean, CSSSelector`	`false`	Allows a tabpanel to be hide when clicked on the button. If it’s `true`, the `hide()` method will be called when `'[data-ui-dismiss=""],[data-ui-dismiss="tablist"]'` is clicked.
`stateMode`	`String`	`'hidden'`	Accepts one of the next values `'hidden','hidden-until-found','inert','class-hidden','class-shown','remove'` Attribute: `data-ui-hide-mode`
`keepPlace`	`Boolean`	`true`	Defines if the tabpanels space is preserved when removed by `stateMode: 'remove'`.

Teleport

Attribute	Type	Default	Description
`teleport`	`CSSSelector, Element, TeleportOptions`	`null`	Object with `TeleportOptions` or `CSSSelector, Element` to set the `to` option for the teleport. Attribute: `data-ui-teleport`

`to`	`CSSSelector, Element`	`null`	Defines where to move the `tabpanel` element.
`position`	`String`	`'beforeend'`	Defines the position for the collapse element once it has been moved. Accepts one of the next values `'beforebegin','afterbegin','beforeend'` or `'afterend'`
`keepPlace`	`Boolean`	`false`	Defines if the `tabpanel` element keeps its original place after being destroyed.

Name	Type	Default	Description
`a11y`	`Boolean, String, A11yOptions`	`'accordion'`	Object with `A11yOptions` or `true` to enable with default options. You can also use one of the following values: `'accordion'` or `'tabs'`.

`role`	`String`	`null`	Adds the `role="tablist"` attribute to the `tablist` element.
`tabRole`	`String`	`'button'`	Adds the `role="tab"` attribute to the `tab` element.
`tabpanelRole`	`String`	`'region'`	Adds the `role="tabpanel"` attribute to the `tabpanel` element.
`ariaOrientation`	`Boolean`	`true`	Adds the `aria-orientation` attribute to the `tablist` element.
`stateAttribute`	`String`	`'aria-expanded'`	You can chose which attribute will be used to indicate the state of the tab.
`tabindex`	`Boolean`	`false`	Adds the `tabindex` attribute to the `tab` element.
`tabpanelTabindex`	`Boolean`	`false`	Adds the `tabindex="0"` attribute to the `tabpanel` element.

Defaults for the a11y:'accordion' value:

{
  role: null,
  tabRole: 'button',
  tabpanelRole: "region",
  ariaOrientation: true,
  stateAttribute: 'aria-expanded',
  tabindex: false,
  tabpanelTabindex: false,
}

Defaults for the a11y:'tabs' value:

{
  role: 'tablist',
  tabRole: 'tab',
  tabpanelRole: "tabpanel",
  ariaOrientation: true,
  stateAttribute: 'aria-selected',
  tabindex: true,
  tabpanelTabindex: true,
}

Hide mode

For more details on how to use, read the State mode section.

Transition

For more details on how to use, read the Transition section.

Methods

Name	Return	Description
`init(options)`	`instance`	Initializes the component.
`destroy(destroyOptions)`	`instance`	Destroys the component. Accepts an object as options `{ remove: false, keepInstance: false, keepState: false }`.
`update(options)`	`instance`	Accepts options as an argument and updates the component.
`on(name, handler)`	`instance`	Allows you to register event handler.
`off(name, handler)`	`instance`	Allows you to remove event handler.
`toggle(tab,toggleOptions,force)`	`promise`	Toggles the tabs’s visibility state between shown and hidden. Accepts `true` or `false` as params which sets the `animated` option or an object `{ animated: true, silent: false }`.
`show(tab,toggleOptions)`	`promise`	Shows the tab. Accepts the same options as `toggle()`.
`hide(tab,toggleOptions)`	`promise`	Hides the tab. Accepts the same options as `toggle()`.
`initTabs()`	`tabInstance`	Searches for all elements specified in the `tab` option and initializes them.
`initTab(Element)`	`tabInstance`	Accepts a tab element and initializes it.
`getTab(Element)`	`tabInstance`	In the list of initiated tabs, finds a tab by the `HTMLElement`, `CSSSelector` or `index`.

Tab Instance Methods

Name	Return	Description
`destroy(destroyOptions)`	`instance, null`	Destroys the tab. Accepts an object `{ cleanStyles: true, remove: false, keepState: false }` where `clean` option removes all generated attributes and classes, and the `remove` removes the tab from the DOM.
`toggle(tab,toggleOptions,force)`	`promise`	Toggles the tab’s visibility state between shown and hidden. Toggles the tabs’s visibility state between shown and hidden. Accepts `true` or `false` as params which sets the `animated` option or an object `{ animated: true, silent: false }`.
`show(tab, toggleOptions)`	`promise`	Shows the tab. Accepts the same options as `toggle()` method.
`hide(tab, toggleOptions)`	`promise`	Hides the tab. Accepts the same options as `toggle()` method.
`toggleDisabled(force)`	`instance`	Toggle `disable` attribute on `tab`.

Class Methods

Name	Return	Description
`data(name?, callback)`	`Class`	Allows you to set default options for components that have the property `data:'name'` or by the attribute `data-tablist="name"`.
`updateDefault(options)`	`default`	Updates default options.
`initAll(root)`	`instance`	Searches for elements in `root`, which defaults to `document` with the attribute `data-ui-tablist` and initializes them.
`get(id or elem)`	`instance`	Searches for an instance by `id` or element (checks the `base` property).
`getOrCreate(id or elem, options)`	`instance`	Searches for an instance by `id` or element (checks the `base` property), if not found - creates a new instance with specified `options`.
`init(options)`	`instance`	Initializes the component.
`destroy(destroyOptions)`	`instance`	Destroys the component. Accepts an object as options `{ remove: false, keepInstance: false, keepState: false }`.
`update(options)`	`instance`	Accepts options as an argument and updates the component.
`toggle(tab,toggleOptions,force)`	`promise`	Toggles the tabs’s visibility state between shown and hidden. Accepts `true` or `false` as params which sets the `animated` option or an object `{ animated: true, silent: false }`.
`show(tab,toggleOptions)`	`promise`	Shows the tab. Accepts the same options as `toggle()`.
`hide(tab,toggleOptions)`	`promise`	Hides the tab. Accepts the same options as `toggle()`.
`initTabs()`	`tabInstance`	Searches for all elements specified in the `tab` option and initializes them.
`initTab(Element)`	`tabInstance`	Accepts a `tab` element and initializes it.
`getTab(Element)`	`tabInstance`	In the list of initiated tabs, finds a tab by the `HTMLElement`, `CSSSelector` or `index`.

Properties

Name	Type	Description
`id`	`String`	The `id` of the `base` element.
`isInit`	`Boolean`	Indicates whether the instance is already initialized.
`opts`	`Object`	Contains the currently applied options for the current breakpoint.
`baseOpts`	`Object`	Contains all options, including the `breakpoints` property.
`base, tablist`	`Element`	All components have a `base` property, which refers to the element through which the component is initialized and where events are fired. `tablist` is a synonym for `base`.
`lastShownTab`	`tabInstance`	The last tab that was shown.
`tabs`	`tabInstance[]`	Returns an array of all tabs.
`shownTabs`	`tabInstance[]`	Returns an array of all shown tabs.

Tab Instance Properties

Name	Type	Description
`id`	`String`	The `id` of the `tabpanel` element.
`tab`	`Element`	Reference to the `tab` element.
`tabpanel`	`Element`	Reference to the `tabpanel` element.
`index`	`Number`	The order number of the `tab`.
`isOpen`	`Boolean`	Indicates whether the `tab` is currently shown.
`isDisabled`	`Boolean`	Indicates whether the `tab` is currently disabled.
`initialPlaceNode`	`Node`	Reference to the node that is in the place of the `tabpanel` element before it was moved or removed.

Class Properties

Name	Type	Description
`Default`	`Object`	Contains the default options for the component.
`DefaultA11y`	`Object`	Contains the default options for the `a11y` option.
`instances`	`Map`	A `Map` that contains all instances of the `Tablist` class.

Events

Name	Arguments	Description
`beforeInit`	`instance`	Event will fired right before initialization.
`init`	`instance`	Fires when initialization has been completed.
`beforeShow`	`instance, tabInstance, {trigger, event}`	Fires immediately when the `show()` method is called.
`show`	`instance, tabInstance, {trigger, event}`	Fires when the element becomes visible, but the CSS transition hasn’t started yet.
`shown`	`instance, tabInstance, {trigger, event}`	Fires when the CSS transition hasn’t been completed.
`beforeHide`	`instance, tabInstance, {trigger, event}`	Fires immediately when the `hide()` method is called.
`hide`	`instance, tabInstance, {trigger, event}`	Fires just before the CSS transition starts.
`hidden`	`instance, tabInstance, {trigger, event}`	Fires when the CSS transition has been completed.
`beforeDestroy`	`instance`	Fires before the instance is destroyed.
`destroy`	`instance`	Fires immediately when the `destroy()` method is called.
`breakpoint`	`instance, breakpoint, prevBreakpoint`	Fires when the breakpoint has been changed.
`any`	`eventName, instance`	Fires on any event occurrence. The first argument contains the name of the event.

Tablist

Getting started

Hash navigation

Tabs

Settings groups

Styles

Accordion

Tabs

Options

Teleport

Accessibility (a11y)

Hide mode

Transition

Methods

Tab Instance Methods

Class Methods

Properties

Tab Instance Properties

Class Properties

Events