Alpine.js Tabs

huxTabs manages active tab state, keyboard focus movement, and optional URL hash synchronization. Use it to attach behavior to your own tablist and panel markup. Panels can either live inside the same x-data scope (owned) or in a separate scope via huxTabPanel (decoupled).

API

huxTabs(config)

Returns an Alpine data object with:

• activeTabId: string | null
• tabItems: Array<{ label: string, id: string }>
• useHash: boolean
• tabsId: string | null
• activeTabIndex: number
• selectTab(tabId: string): void
• focusTab(tabId: string): void
• focusNextTab(): void
• focusPreviousTab(): void
• focusFirstTab(): void
• focusLastTab(): void

Internal helper methods are private implementation details and are not part of the supported API contract.

huxTabPanel(config)

Returns an Alpine data object for a decoupled tab panel with:

• isActive: boolean
• tabsId: string
• tabId: string

Options

huxTabs

• tabItems: Array<{ label: string, id: string }> (default: [])
• activeTab: string (optional initial active id)
• useHash: boolean (default: false)
• id: string (optional; enables hux-tabs:{id}:change events for decoupled panels)

huxTabPanel

• tabsId: string (required; matches the id passed to huxTabs)
• tabId: string (required; the tab id this panel belongs to)

Quick Start

<div
  x-data="huxTabs({
    tabItems: [
      { label: 'General', id: 'general' },
      { label: 'Security', id: 'security' }
    ],
    useHash: true
  })"
>
  <div role="tablist" aria-label="Settings">
    <template x-for="tabItem in tabItems" x-bind:key="tabItem.id">
      <button
        type="button"
        role="tab"
        x-bind:id="`tab-${tabItem.id}`"
        x-bind:aria-controls="`panel-${tabItem.id}`"
        x-bind:aria-selected="(activeTabId === tabItem.id).toString()"
        x-bind:tabindex="activeTabId === tabItem.id ? '0' : '-1'"
        x-on:click="selectTab(tabItem.id)"
        x-on:keydown.right.prevent="focusNextTab()"
        x-on:keydown.left.prevent="focusPreviousTab()"
        x-text="tabItem.label"
      ></button>
    </template>
  </div>

  <section
    id="panel-general"
    role="tabpanel"
    aria-labelledby="tab-general"
    x-show="activeTabId === 'general'"
    x-cloak
  >
    ...
  </section>
</div>

Common Usage Patterns

Initialize Active Tab From Hash

huxTabs({
  tabItems: [
    { label: 'General', id: 'general' },
    { label: 'Security', id: 'security' },
    { label: 'Notifications', id: 'notifications' },
  ],
  useHash: true,
})

Provide Explicit Initial Tab

huxTabs({
  tabItems: [
    { label: 'General', id: 'general' },
    { label: 'Security', id: 'security' },
  ],
  activeTab: 'security',
})

Decoupled Panels

Use id on huxTabs and huxTabPanel on each panel to place tablist and panels in separate DOM scopes.

<div
  x-data="huxTabs({
    id: 'settings',
    tabItems: [
      { label: 'General', id: 'general' },
      { label: 'Security', id: 'security' }
    ]
  })"
>
  <div role="tablist" aria-label="Settings">
    <template x-for="tabItem in tabItems" x-bind:key="tabItem.id">
      <button
        type="button"
        role="tab"
        x-bind:id="`tab-${tabItem.id}`"
        x-bind:aria-controls="`panel-${tabItem.id}`"
        x-bind:aria-selected="(activeTabId === tabItem.id).toString()"
        x-bind:tabindex="activeTabId === tabItem.id ? '0' : '-1'"
        x-on:click="selectTab(tabItem.id)"
        x-on:keydown.right.prevent="focusNextTab()"
        x-on:keydown.left.prevent="focusPreviousTab()"
        x-text="tabItem.label"
      ></button>
    </template>
  </div>
</div>

<section
  id="panel-general"
  role="tabpanel"
  aria-labelledby="tab-general"
  tabindex="0"
  x-data="huxTabPanel({ tabsId: 'settings', tabId: 'general' })"
  x-show="isActive"
  x-cloak
>
  ...
</section>

<section
  id="panel-security"
  role="tabpanel"
  aria-labelledby="tab-security"
  tabindex="0"
  x-data="huxTabPanel({ tabsId: 'settings', tabId: 'security' })"
  x-show="isActive"
  x-cloak
>
  ...
</section>

Behavior Contract

• Invalid tab items are filtered out during initialization.
• When useHash is enabled, the component decodes location.hash and uses it when it matches a known tab id.
• If initial active id is missing or invalid, active tab falls back to the first valid tab id.
• selectTab() ignores unknown ids and only updates state for valid ids.
• focusNextTab() and focusPreviousTab() wrap at boundaries.
• When useHash is enabled, selectTab() updates hash with history.replaceState.
• When id is set, selectTab() dispatches hux-tabs:{id}:change on window with { tabId } in event.detail. No event is dispatched when activeTabId is null.
• When id is set, the initial active tab is also dispatched via hux-tabs:{id}:change after all components in the current render have initialized. No event is dispatched when tabItems is empty.
• huxTabPanel toggles isActive on every hux-tabs:{tabsId}:change event — true when the event’s tabId matches its own tabId, false otherwise.

Error Handling

• Malformed hash decoding is caught and ignored without throwing.
• Unknown tab ids no-op in selectTab() and focus helpers.
• Empty tab arrays initialize with activeTabId = null.
• huxTabPanel logs a console error and no-ops when tabsId or tabId is missing.

Accessibility Notes

• Use ARIA tabs pattern roles and relationships: role="tablist", role="tab", role="tabpanel", aria-controls, and aria-labelledby.
• Keep roving tabindex (0 for active tab, -1 for inactive tabs) so keyboard focus order is predictable.
• Wire arrow keys plus Home/End for expected tab keyboard behavior.
• Keep tab controls as button type="button" and ensure visible active-state contrast.

Notes

• Hash sync uses replaceState, so tab changes do not add browser history entries.
• Events emitted when id is set:
  • hux-tabs:{id}:change — dispatched on window with { tabId: string } detail on init and on every selectTab() call. Not dispatched when activeTabId is null (empty tab list).
• Owned panels (no id needed) still work via x-show="activeTabId === 'general'" inside the same x-data scope.