Skip to content

basic-tab-strip

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

basic-tab-strip

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
dist
dist
 
 
src
src
 
 
README.md
README.md
 
 
globals.js
globals.js
 
 
index.html
index.html
 
 
package.json
package.json
 
 

README.md

API Documentation

TabStrip ⇐ ElementBase

A set of pages with a tab strip governing which page is shown.

This stock combination applies the TabStripMixin to a basic-modes element. If you'd like to create something more complex than this arrangement, you can use either of those elements on its own.

Since this component uses TabStripMixin, it obtains the names of the individual tabs from a child's aria-label property. Example:

<basic-tabs>
  <div aria-label="One">Page one</div>
  <div aria-label="Two">Page two</div>
  <div aria-label="Three">Page three</div>
</basic-tabs>

Kind: global class Extends: ElementBase
Mixes: ClickSelectionMixin , ContentItemsMixin , DirectionSelectionMixin , DistributedChildrenContentMixin , GenericMixin , KeyboardMixin , KeyboardDirectionMixin , SingleSelectionMixin

tabStrip.canSelectNext : boolean

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 SingleSelection mixin.

tabStrip.canSelectPrevious : boolean

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 SingleSelection mixin.

tabStrip.content : Array.<HTMLElement>

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

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

"content-changed"

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

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

tabStrip.contentChanged()

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 DistributedChildrenContent mixin.

tabStrip.generic : Boolean

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

TabStrip.goDown()

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

Kind: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goEnd()

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: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goLeft()

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

Kind: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goRight()

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

Kind: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goStart()

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: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goUp()

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

Kind: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.itemAdded(item)

This method is invoked whenever a new item is added to the list.

The default implementation of this method does nothing. You can override this to perform per-item initialization.

Kind: static method of TabStrip. Defined by ContentItems#symbols mixin.

Param Type Description
item HTMLElement The item that was added.

TabStrip.itemAdded(item)

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: static method of TabStrip. Defined by SingleSelection#symbols mixin.

Param Type Description
item HTMLElement the item being added

tabStrip.items : Array.<HTMLElement>

The current set of items in the list. See the top-level documentation for mixin for a description of how items differ from plain content.

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

"items-changed"

Fires when the items in the list change.

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

TabStrip.itemsChanged()

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: static method of TabStrip. Defined by ContentItems#symbols mixin.

TabStrip.itemSelected(item, selected)

The selection state for a single item has changed.

Invoke this method to signal that the selected state of the indicated item has changed. By default, this applies a selected CSS class if the item is selected, and removed it if not selected.

Kind: static method of TabStrip. Defined by ContentItems#symbols mixin.

Param Type Description
item HTMLElement The item whose selection state has changed.
selected boolean True if the item is selected, false if not.

TabStrip.itemSelected(item, selected)

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: static method of TabStrip. Defined by SingleSelection#symbols mixin.

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

TabStrip.keydown(event) ⇒ boolean

Handle the indicated keyboard event.

The default implementation of this method does nothing. This will typically be handled by other mixins.

Kind: static method of TabStrip. Defined by Keyboard#symbols mixin. Returns: boolean - true if the event was handled

Param Type Description
event KeyboardEvent the keyboard event

tabStrip.navigationAxis : string

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.

"selected-index-changed"

Fires when the selectedIndex property changes.

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

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

"selected-item-changed"

Fires when the selectedItem property changes.

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

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

tabStrip.selectedIndex : number

The index of the item which is currently selected.

A selectedIndex of -1 indicates there is no selection. Setting this property to -1 will remove any existing selection.

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

tabStrip.selectedItem : object

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

Setting this property to null deselects any currently-selected item. Setting this property to an object that is not in the list has no effect.

TODO: Even if selectionRequired, can still explicitly set selectedItem to null. TODO: If selectionRequired, leave selection alone?

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

tabStrip.selectFirst()

Select the first item in the list.

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

tabStrip.selectionRequired : boolean

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

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

tabStrip.selectionWraps : boolean

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

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

tabStrip.selectLast()

Select the last item in the list.

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

tabStrip.selectNext()

Select the next item in the list.

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

tabStrip.selectPrevious()

Select the previous item in the list.

If the list has no selection, the last item will be selected.

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

tabStrip.tabPosition : string

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: "&quot;top&quot;"

TabStrip

A template mixin which adds 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:

<basic-tab-strip>
  <basic-modes aria-label="Panels">
    <div aria-label="One">Page one</div>
    <div aria-label="Two">Page two</div>
    <div aria-label="Three">Page three</div>
  </basic-modes>
</basic-tab-strip>

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 GenericMixin 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 GenericMixin property/attribute to false.

Kind: global class

tabStrip.canSelectNext : boolean

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 SingleSelection mixin.

tabStrip.canSelectPrevious : boolean

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 SingleSelection mixin.

tabStrip.content : Array.<HTMLElement>

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

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

"content-changed"

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

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

tabStrip.contentChanged()

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 DistributedChildrenContent mixin.

tabStrip.generic : Boolean

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

TabStrip.goDown()

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

Kind: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goEnd()

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: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goLeft()

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

Kind: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goRight()

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

Kind: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goStart()

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: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.goUp()

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

Kind: static method of TabStrip. Defined by KeyboardDirection#symbols mixin.

TabStrip.itemAdded(item)

This method is invoked whenever a new item is added to the list.

The default implementation of this method does nothing. You can override this to perform per-item initialization.

Kind: static method of TabStrip. Defined by ContentItems#symbols mixin.

Param Type Description
item HTMLElement The item that was added.

TabStrip.itemAdded(item)

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: static method of TabStrip. Defined by SingleSelection#symbols mixin.

Param Type Description
item HTMLElement the item being added

tabStrip.items : Array.<HTMLElement>

The current set of items in the list. See the top-level documentation for mixin for a description of how items differ from plain content.

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

"items-changed"

Fires when the items in the list change.

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

TabStrip.itemsChanged()

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: static method of TabStrip. Defined by ContentItems#symbols mixin.

TabStrip.itemSelected(item, selected)

The selection state for a single item has changed.

Invoke this method to signal that the selected state of the indicated item has changed. By default, this applies a selected CSS class if the item is selected, and removed it if not selected.

Kind: static method of TabStrip. Defined by ContentItems#symbols mixin.

Param Type Description
item HTMLElement The item whose selection state has changed.
selected boolean True if the item is selected, false if not.

TabStrip.itemSelected(item, selected)

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: static method of TabStrip. Defined by SingleSelection#symbols mixin.

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

TabStrip.keydown(event) ⇒ boolean

Handle the indicated keyboard event.

The default implementation of this method does nothing. This will typically be handled by other mixins.

Kind: static method of TabStrip. Defined by Keyboard#symbols mixin. Returns: boolean - true if the event was handled

Param Type Description
event KeyboardEvent the keyboard event

tabStrip.navigationAxis : string

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.

"selected-index-changed"

Fires when the selectedIndex property changes.

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

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

"selected-item-changed"

Fires when the selectedItem property changes.

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

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

tabStrip.selectedIndex : number

The index of the item which is currently selected.

A selectedIndex of -1 indicates there is no selection. Setting this property to -1 will remove any existing selection.

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

tabStrip.selectedItem : object

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

Setting this property to null deselects any currently-selected item. Setting this property to an object that is not in the list has no effect.

TODO: Even if selectionRequired, can still explicitly set selectedItem to null. TODO: If selectionRequired, leave selection alone?

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

tabStrip.selectFirst()

Select the first item in the list.

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

tabStrip.selectionRequired : boolean

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

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

tabStrip.selectionWraps : boolean

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

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

tabStrip.selectLast()

Select the last item in the list.

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

tabStrip.selectNext()

Select the next item in the list.

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

tabStrip.selectPrevious()

Select the previous item in the list.

If the list has no selection, the last item will be selected.

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

tabStrip.tabPosition : string

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: "&quot;top&quot;"