Tablist
Updated on September 7, 2024Source codeTests
useTablist is a composable that implements the UI logic needed for a reactive, accessible tablist interface.
It follows WAI-ARIA authoring practices and allows you to easily customize accessibility features.
Example
Community-led conservation works. Maliasili supports grassroots African conservation organizations that do critical work at the nexus of poverty and conservation. They provide customized ongoing support to these community-based organizations to improve their performance and accelerate their impact -- it’s kinda like one of our fellows programs. The results so far have been remarkable, and we see potential for Maliasili to grow the impact of local conservation organizations in important ecological landscapes across Africa and beyond.
00Create a tablist
To create a tablist, call the useTablist function, which accepts one optional options object as its only parameter.
<!-- MyComponent.vue -->
<template>...</template>
<script setup>
import { useTablist } from '@baleada/vue-features'
const tablist = useTablist([options])
</script>
Here's a breakdown of the options object:
transitionAn object with one property: panel.
Pass an object to transition.panel, specifying a transition or animation that useTablist should apply to each tab panel as they enter and leave visibility.
See the How to format enter/leave transitions section of the show docs for more guidance.
initialSelected0ability() => 'enabled'A status option that should resolve to enabled for each enabled tab, and disabled for each disabled tab.
useTablist uses this information to decide which tabs are eligible to receive focus and/or be selected.
orientationhorizontalselectsOnFocustrueloopstruedisabledTabsReceiveFocustrueIndicates whether or not your tablist can transfer focus to disabled tabs.
If you set disabledTabsReceiveFocus to false, you should be confident that assistive tech users don't need or want to read the labels of disabled tabs, or that they have another way to access that content.
Note that even when disabledTabsReceiveFocus is true, it's never possible to select disabled tabs.
panelContentsFocusabilityA status option that should resolve to focusable when tab panel contents can receive focus, and not focusable when tab panel contents cannot receive focus.
useTablist uses this information to implement an accessibility feature for you: the tab panel should only be included in the page's tab order when tab panel contents are not focusable.
Use your tablist
useTablist returns a tablist—an object with tools you can use to connect useTablist's UI logic to your markup.
Here's a breakdown of that object:
rootroot.ref should be bound to the DOM element that serves as your tablist's root.
tabsA multiple element API object.
Pass the index-based position (Number) of the current tab as the only argument for tabs.ref, and its returned function ref should be bound to the DOM element that serves as that tab.
It's recommended that you render the tabs with v-for, get the index from your v-for statement, and bind the function ref to the v-for element.
panelsA multiple element API object.
Pass the index-based position (Number) of the current panel as the only argument for panels.ref, and its returned function ref should be bound to the DOM element that serves as that panel.
It's recommended that you render the panels with v-for, get the index from your v-for statement, and bind the function ref to the v-for element.
focusedselectedisAn object with two properties: focused and selected.
Each property holds a method that requires an index (Number) as its only parameter.
Given the index, is.focused returns a boolean indicating whether or not that tab is focused, and is.selected returns a boolean indicating whether or not that tab is selected.
is.focused and is.selected read from reactive references, so their boolean return values are fully reactive when used in Vue templates, watchers, and computed references.
getStatuses(index)A function that requires an index (Number) as its only parameter, and returns a three-item array indicating the statuses (Strings) of the tab at that index.
The first item will be focused or blurred, the second item will be selected or deselected and the third item will be enabled or disabled.
focusAn object containing all the methods described in the eligible focus guide.
You can use these methods to programmatically transfer focus in a smarter way, taking enabled/disabled state and other customizable conditions into account.
selectAn object containing all the methods described in the eligible picking guide.
You can use these methods to programmatically select tabs in a smarter way, taking enabled/disabled state and other customizable conditions into account.
Note that tablists can never be multiselectable, so you can only pass a single index to the select.exact method—an array of selected indices is not possible.
Here's a more complete example of how to use your tablist and bind the various function refs:
<!-- MyComponent.vue -->
<template>
<div :ref="tablist.root.ref()">
<div
v-for="({ tab }, index) in metadata"
:key="tab"
:ref="tablist.tabs.ref(index)"
>
{{ tab }}
</div>
<div
v-for="({ tab, panel }, index) in metadata"
:key="tab"
:ref="tablist.panels.ref(index)"
>
{{ panel }}
</div>
</div>
</template>
<script setup>
import { ref, computed } from 'vue'
import { useTablist } from '@baleada/vue-features'
const metadata = ref([
{ tab: 'Educate Girls', panel: 'https://www.educategirls.ngo/' },
{ tab: 'Kheyti', panel: 'https://www.kheyti.com/' },
{ tab: 'One Heart Worldwide', panel: 'https://oneheartworldwide.org/' },
])
const tablist = useTablist()
</script>
Extend the tablist
The following extensions are compatible with your textbox:
