API Documentation

TabStrip ⇐ ElementBase

A strip of tabs for selecting one of the component's children.

The component creates a tab to represent each of its light DOM children.
The tab name is obtained by examining the children for an aria-label
property.

Use tabs when you want to provide a large set of options or elements than
can comfortably fit inline, the options can be coherently grouped into pages,
and you want to avoid making the user navigate to a separate page. Tabs work
best if you only have a small handful of pages, say 2–7.

The basic-tab-strip component does not define how a selected child is
represented. If you're looking for the standard behavior of just showing only
the selected child, you can use this component in combination with the
separate basic-modes component. A typical arrangement:

The above combination is so common it is provided as a single component,
basic-tabs.

The user can select a tab with the mouse or touch, as well as by through the
keyboard. Each tab appears as a separate button in the tab order.
Additionally, if the focus is currently on a tab, the user can quickly
navigate between tabs with the left/right arrow keys (or, if the tabs are
in vertical position, the up/down arrow keys).

By default, the tabs are shown grouped to the left, where each tab is only
as big as necessary. You can apply the spread CSS class to a
basic-tab-strip element for a variant appearance in which the available width
of the element is divided up equally among tabs.

The generic default styling of the tab strip will present the classic
skeumorphic look of rounded tabs attached to a surface. You can remove this
styling by setting the generic property/attribute to false.

Kind: global class
Extends: ElementBase
Mixes: ContentFirstChildTarget
, DirectionSelection
, DistributedChildrenAsContent
, Generic
, ItemsSelection
, KeyboardDirection
, ObserveContentChanges
, TargetSelection

* TabStrip ⇐ ElementBase
* .applySelection(item, selected)
* .canSelectNext : boolean
* .canSelectPrevious : boolean
* .content : Array.<HTMLElement>
* "content-changed"
* .contentChanged()
* .generic : Boolean
* .goDown()
* .goEnd()
* .goLeft()
* .goRight()
* .goStart()
* .goUp()
* .itemAdded(item)
* .items : Array.<HTMLElement>
* .itemsChanged()
* .navigationAxis : string
* "selected-index-changed"
* "selected-item-changed"
* .selectedIndex : number
* .selectedItem : HTMLElement
* .selectedItem : object
* .selectFirst()
* .selectionRequired : boolean
* .selectionWraps : boolean
* .selectionWraps : boolean
* .selectLast()
* .selectNext()
* .selectPrevious()
* .tabPosition : string
* .target : HTMLElement
* .target : HTMLElement

$3

Apply the indicate selection state to the item.

The default implementation of this method does nothing. User-visible
effects will typically be handled by other mixins.

Kind: instance method of TabStrip. Defined by ItemsSelection mixin.

| Param | Type | Description |
| --- | --- | --- |
| item | HTMLElement | the item being selected/deselected |
| selected | boolean | true if the item is selected, false if not |

$3

True if the selection can be moved to the next item, false if not (the
selected item is the last item in the list).

Kind: instance property of TabStrip. Defined by ItemsSelection mixin.

$3

True if the selection can be moved to the previous item, false if not
(the selected item is the first one in the list).

Kind: instance property of TabStrip. Defined by ItemsSelection mixin.

$3

The content of this component, defined to be the flattened array of
children distributed to the component.

Kind: instance property of TabStrip. Defined by DistributedChildrenAsContent mixin.

$3

This event is raised when the component's contents (including distributed
children) have changed.

Kind: event emitted by TabStrip. Defined by ObserveContentChanges mixin.

$3

Invoked when the contents of the component (including distributed
children) have changed.

This method is also invoked when a component is first instantiated; the
contents have essentially "changed" from being nothing. This allows the
component to perform initial processing of its children.

Kind: instance method of TabStrip. Defined by ObserveContentChanges mixin.

$3

True if the component would like to receive generic styling.

This property is true by default — set it to false to turn off all
generic styles. This makes it easier to apply custom styling; you won't
have to explicitly override styling you don't want.

Kind: instance property of TabStrip. Defined by Generic mixin.
Default: true

$3

Invoked when the user wants to go/navigate down.
The default implementation of this method does nothing.

Kind: instance method of TabStrip. Defined by KeyboardDirection mixin.

$3

Invoked when the user wants to go/navigate to the end (e.g., of a list).
The default implementation of this method does nothing.

Kind: instance method of TabStrip. Defined by KeyboardDirection mixin.

$3

Invoked when the user wants to go/navigate left.
The default implementation of this method does nothing.

Kind: instance method of TabStrip. Defined by KeyboardDirection mixin.

$3

Invoked when the user wants to go/navigate right.
The default implementation of this method does nothing.

Kind: instance method of TabStrip. Defined by KeyboardDirection mixin.

$3

Invoked when the user wants to go/navigate to the start (e.g., of a
list). The default implementation of this method does nothing.

Kind: instance method of TabStrip. Defined by KeyboardDirection mixin.

$3

Invoked when the user wants to go/navigate up.
The default implementation of this method does nothing.

Kind: instance method of TabStrip. Defined by KeyboardDirection mixin.

$3

Handle a new item being added to the list.

The default implementation of this method simply sets the item's
selection state to false.

Kind: instance method of TabStrip. Defined by ItemsSelection mixin.

| Param | Type | Description |
| --- | --- | --- |
| item | HTMLElement | the item being added |

$3

The current set of items in the list.

Kind: instance property of TabStrip. Defined by TargetSelection mixin.

$3

This method is invoked when the underlying contents change. It is also
invoked on component initialization – since the items have "changed" from
being nothing.

Kind: instance method of TabStrip. Defined by TargetSelection mixin.

$3

Indicates the direction of permitted navigation with the keyboard.

Accepted values are "horizontal", "vertical", or "both" (the default).
If this property is "horizontal", the Up Arrow and Down Arrow keys will
be ignored. Conversely, if this is "vertical", the Left Arrow and Right
Arrow keys will be ignored.

Kind: instance property of TabStrip. Defined by KeyboardDirection mixin.

$3

Fires when the selectedIndex property changes.

Kind: event emitted by TabStrip. Defined by ItemsSelection mixin.

| Param | Type | Description |
| --- | --- | --- |
| detail.selectedIndex | number | The new selected index. |

$3

Fires when the selectedItem property changes.

Kind: event emitted by TabStrip. Defined by ItemsSelection mixin.

| Param | Type | Description |
| --- | --- | --- |
| detail.selectedItem | HTMLElement | The new selected item. |
| detail.previousItem | HTMLElement | The previously selected item. |

$3

The index of the item which is currently selected.

If selectionWraps is false, the index is -1 if there is no selection.
In that case, setting the index to -1 will deselect any
currently-selected item.

Kind: instance property of TabStrip. Defined by ItemsSelection mixin.

$3

The currently selected item, or null if there is no selection.

Kind: instance property of TabStrip. Defined by TargetSelection mixin.

$3

The currently selected item, or null if there is no selection.

Setting this property to null deselects any currently-selected item.

Kind: instance property of TabStrip. Defined by ItemsSelection mixin.

$3

Select the first item in the list.

Kind: instance method of TabStrip. Defined by ItemsSelection mixin.

$3

True if the list should always have a selection (if it has items).

Kind: instance property of TabStrip. Defined by ItemsSelection mixin.
Default: false

$3

True if selection navigations wrap from last to first, and vice versa.

Kind: instance property of TabStrip. Defined by ItemsSelection mixin.
Default: false

$3

True if selection navigations wrap from last to first, and vice versa.

Kind: instance property of TabStrip. Defined by TargetSelection mixin.
Default: {false}

$3

Select the last item in the list.

Kind: instance method of TabStrip. Defined by ItemsSelection mixin.

$3

Select the next item in the list.

Kind: instance method of TabStrip. Defined by ItemsSelection mixin.

$3

Select the previous item in the list.

Kind: instance method of TabStrip. Defined by ItemsSelection mixin.

$3

The position of the tab strip relative to the element's children. Valid
values are "top", "left", "right", and "bottom".

Kind: instance property of TabStrip
Default: "\"top\""

$3

Gets/sets the current target of the component.

Kind: instance property of TabStrip. Defined by ContentFirstChildTarget mixin.

$3

Gets/sets the target element to which this component will delegate
selection actions.

Kind: instance property of TabStrip. Defined by TargetSelection mixin.