Wagtail client-side components
    Preparing search index...

    Class TabsController

    Adds the ability for the controlled elements to behave as selectable tabs where one panel will be active at a time.

    • Allow keyboard control, focusing on the first selected tab and then using arrows to navigate/switch between active tabs.
    • All tabs, triggers and tab panels must be nested in an element within the scope of the controller.
    • All tab (buttons/links) need the role="tab" attribute and either a href with the tab content id with the target tab or a aria-controls set to a target tab.
    • Tab (buttons/links as trigger targets) are those that are wrapped in an element with the role="tablist" attribute.
    • Tab panels must have the role="tabpanel" attribute and and id attribute that matches the href of the tab link with the target 'panel'.
    • Use the target 'trigger' on an Anchor link and set the href to the id of the tab you would like to trigger or use action params.

    Uses the tabs pattern from the WAI-ARIA Authoring Practices Guide (APG).

    https://www.w3.org/WAI/ARIA/apg/patterns/tabs/

    <div data-controller="w-tabs">
      <div role="tablist">
        <a id="edit-tab-label" href="#panel-edit" role="tab" data-w-tabs-target="trigger" data-action="w-tabs#select:prevent">Edit</a>
        <a id="sett-tab-label" href="#panel-sett" role="tab" data-w-tabs-target="trigger" data-action="w-tabs#select:prevent" aria-selected="true">Settings</a>
      </div>
      <div class="tab-content">
        <section id="panel-edit" role="tabpanel" aria-labelledby="edit-tab-label" data-w-tabs-target="panel">Edit</section>
        <section id="panel-sett" role="tabpanel" aria-labelledby="tab-2" data-w-tabs-target="panel">Settings</section>
       </div>
    </div>

    Example: - Full tabs with class changes, history/location handling, keyboard controls, selection from inside & extra trigger

    <div data-controller="w-tabs" data-action="popstate@window->w-tabs#select" data-w-tabs-active-class="animate-in" data-w-tabs-use-location-value="true">
      <div role="tablist" data-action="keydown.right->w-tabs#selectNext keydown.left->w-tabs#selectPrevious keydown.home->w-tabs#selectFirst keydown.end->w-tabs#selectLast">
        <a id="tab-1" href="#panel-1" role="tab" data-w-tabs-target="trigger" data-action="w-tabs#select:prevent">Tab 1</a>
        <a id="tab-2" href="#panel-2" role="tab" data-w-tabs-target="trigger" data-action="w-tabs#select:prevent">Tab 2</a>
      </div>
      <div class="tab-content">
        <section id="panel-1" role="tabpanel" aria-labelledby="tab-1" data-w-tabs-target="panel" data-action="w-focus:focus->w-tabs#selectInside">
          Tab 1 content
        </section>
        <section id="panel-2" role="tabpanel" aria-labelledby="tab-2" data-w-tabs-target="panel" data-action="w-focus:focus->w-tabs#selectInside">
          Tab 2 content
        </section>
      </div>
      <button type="button" data-action="w-tabs#select" data-w-tabs-target="trigger" data-w-tabs-id-param="panel-1" data-w-tabs-focus-param="true">Extra trigger for Tab 1</button>
    </div>

    Hierarchy

    • Controller
      • TabsController
    Index

    Constructors

    constructor

    Properties

    activeClasses activePanelIdValue context historyStateKey panelTargetConnected panelTargetDisconnected panelTargets tabs triggerTargetConnected triggerTargetDisconnected triggerTargets useLocationValue blessings classes outlets targets values

    Accessors

    application classes data element identifier locationPanelId outlets scope targets validatedTabs shouldLoad

    Methods

    afterTransition disconnect dispatch initialize select selectFirst selectInside selectLast selectNext selectPrevious setInitialPanel syncLocation afterLoad

    Events

    activePanelIdValueChanged connect

    Constructors

    • Parameters

      • context: Context

      Returns TabsController

    Properties

    activeClasses: string[]

    Classes to add to the panel content when active.

    activePanelIdValue: string

    The id of the panel (not the tab/trigger) that's currently active.

    context: Context
    historyStateKey: string = 'tabs-panel-id'

    The key for reading/applying history state if locationSync is enabled, based on the controller's identifier.

    panelTargetConnected: (target: HTMLElement) => void
    panelTargetDisconnected: (target: HTMLElement) => void
    panelTargets: HTMLElement[]

    Tab content panels, with role='tabpanel', showing the content for each tab.

    tabs: (HTMLAnchorElement | HTMLButtonElement)[] = []

    Trigger elements that are the primary tabs, with role='tab' within the role='tablist'.

    triggerTargetConnected: (target: HTMLElement) => void
    triggerTargetDisconnected: (target: HTMLElement) => void
    triggerTargets: (HTMLAnchorElement | HTMLButtonElement)[]

    Any elements within the controller's scope that may select a specific panel.

    useLocationValue: boolean

    If true, the selected tab will sync with the URL hash and the URL hash will be checked on load for a selected tab panel (or panel contents).

    blessings: (<T>(constructor: Constructor<T>) => any)[]
    classes: string[] = ...
    outlets: string[]
    targets: string[] = ...
    values: {
        activePanelId: { default: string; type: StringConstructor };
        useLocation: { default: boolean; type: BooleanConstructor };
    } = ...

    Accessors

    • get application(): Application

      Returns Application

    • get classes(): ClassMap

      Returns ClassMap

    • get data(): DataMap

      Returns DataMap

    • get element(): ElementType

      Returns ElementType

    • get identifier(): string

      Returns string

    • get outlets(): OutletSet

      Returns OutletSet

    • get scope(): Scope

      Returns Scope

    • get targets(): TargetSet

      Returns TargetSet

    • get shouldLoad(): boolean

      Returns boolean

    Methods

    • Handles the completion of a transition or animation on the given element. If transitions are enabled via CSS, the Promise returned will resolve when either the animation is finished or the transition timeout value is reached. If transitions are not enabled, an immediately-resolved Promise is returned.

      Parameters

      Returns Promise<HTMLElement>

    • Returns void

    • Parameters

      • eventName: string
      • Optional__namedParameters: Partial<
            {
                bubbles: boolean;
                cancelable: boolean;
                detail: Object;
                prefix: string;
                target: Element
                | Window
                | Document;
            },
        >

      Returns CustomEvent<Object>

    • Returns void

    • Set the active panel based on a provided id from the event or a target element which is assumed to be a tab element, that has been passed in. If the focus parameter is set to true, the target element will be focused if it is a valid tab, otherwise the matching tab will be focused.

      Parameters

      Returns any

    • Set the active panel based on the next tab in the DOM order. If the current active panel is already the last tab, keep this panel active.

      Parameters

      Returns any

    • Set the active panel based on the previous tab in the DOM order. If the current active panel is already the first tab, keep this panel active.

      Parameters

      Returns any

    • If the initial panel is found, set it as the active panel, if the value is already set (from the DOM value), trigger the value changed callback.

      If no initial panel is found, the first tab will be selected.

      Returns any

      The initial active panel is based on:

      1. Location (URL) based if enabled & matching location found
      2. Existing value set in the HTML (can be overridden from the param)
      3. First tab with aria-selected='true'
      4. Fall back to selection of the first panel

    • Update the URL (location) hash based on the active panel id, only if configured to be syncing location. If state is available, add a new history item to the stack.

      Returns string | null

    • Parameters

      • _identifier: string
      • _application: Application

      Returns void

    Events

    • Whenever the active panel has changed, handle transitions and selection from the current to the new panels.

      Set the non-active panels to tabindex="-1" and aria-selected="false" so that they are not focusable and not selected, allowing the tabs to be controlled via keyboard arrows and Home/End keys.

      Parameters

      • currentPanelId: string
      • previousPanelId: string

      Returns void

      TabsController#selected - When a new panel is about to be active, fires on the triggers/tab for that panel. TabsController#selected

      TabsController#changed - When a new panel is active, fires on the panel that is now active. TabsController#changed

    • Validate & clean targets, set the initial active panel, hide any non active panels then dispatch ready.

      Once ready, allow for targets to change and reset the tabs & validation.

      Returns void

      TabsController#ready - When the controller is ready and has set the initial active panel. TabsController#ready

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Accessors
    Methods
    Events