TabButton

Generic tab button with a text label
Page one
Page two
Page three
Demo: By default, Tabs creates a TabButton for each tab panel

Overview

This component is intended to show a text label, and styled by default to look like a classic tab. Tabs uses this class as the default proxy for tab panels — for each tab panel, Tabs will create a corresponding TabButton.

The button supports a position property that controls whether the tab should style itself appropriately for appearing at the top, bottom, left or right edge of the panels it controls. Visually, the tab button will have no interior border on the edge it shares with the panels, so that the tab button and panel appear to exist on the same surface. By default, the two corners opposite that edge are rounded in skeumorphic reference to the real-world tabs on cardstock folders.

See also

Tabs
Basic tabs structure for navigation and configuration
TabStrip
Strip of tab buttons

API

Class hierarchy:

The element defines the following shadow parts:

  • inner: the inner standard HTML element

This element is used as a shadow part in Tabs.

booleanAttributeValue(name, value) static method

Given a string value for a named boolean attribute, return true if the value is either: a) the empty string, or b) a case-insensitive match for the name.

This is native HTML behavior; see the MDN documentation on boolean attributes for the reasoning.

Given a null value, this return false. Given a boolean value, this return the value as is.

Parameters:

  • name: string
  • value: string|boolean|null

Defined by AttributeMarshallingMixin

contentSlot property

See contentSlot.

Defined by SlotContentMixin

defaultState property

The default state for the component. This can be extended by mixins and classes to provide additional default state.

Type: PlainObject

Defined by ReactiveMixin

delegatesFocus property

Returns true if the component is delegating its focus.

A component using DelegateFocusMixin will always have this property be true unless a class takes measures to override it.

Type: boolean

Default: true

Defined by DelegateFocusMixin

extends property

The tag name of the standard HTML element extended by this class.

Defined by WrappedStandardElement

ids property

A convenient shortcut for looking up an element by ID in the component's Shadow DOM subtree.

Example: if component's template contains a shadow element <button id="foo">, you can use the reference this[ids].foo to obtain the corresponding button in the component instance's shadow tree. The ids property is simply a shorthand for getElementById, so this[ids].foo is the same as this[shadowRoot].getElementById('foo').

Type: object

Defined by ShadowTemplateMixin

inner property

Returns a reference to the inner standard HTML element.

Type: HTMLElement

Defined by WrappedStandardElement

position property

The position of the tab strip with respect to the associated tab panels.

Setting this property does not actually change the tab buttons's position in the document, but lets the tab button know how it should display itself. The standard apperance of TabButton is to hide the visible border between the tab button and its associated panel, and position is used to determine which edge's border should be hidden.

Type: 'bottom'|'left'|'right'|'top'

Default: 'top'

render(changed) method

Render the indicated changes in state to the DOM.

The default implementation of this method does nothing. Override this method in your component to update your component's host element and any shadow elements to reflect the component's new state. See the rendering example.

Be sure to call super in your method implementation so that your component's base classes and mixins have a chance to perform their own render work.

Parameters:

  • changed: ChangedFlagsdictionary of flags indicating which state members have changed since the last render

Defined by ReactiveMixin

renderChanges() method

Render any pending component changes to the DOM.

This method does nothing if the state has not changed since the last render call.

ReactiveMixin will invoke this method following a setState call; you should not need to invoke this method yourself.

This method invokes the internal render method, then invokes the rendered method.

Defined by ReactiveMixin

rendered(changed) method

Perform any work that must happen after state changes have been rendered to the DOM.

The default implementation of this method does nothing. Override this method in your component to perform work that requires the component to be fully rendered, such as setting focus on a shadow element or inspecting the computed style of an element. If such work should result in a change in component state, you can safely call setState during the rendered method.

Be sure to call super in your method implementation so that your component's base classes and mixins have a chance to perform their own post-render work.

Parameters:

  • changed: ChangedFlags

Defined by ReactiveMixin

selected property

True if the element is currently selected.

Type: boolean

Default: false

Defined by SelectableMixin

selectedchange event

Raised when the selected property changes.

Defined by SelectableMixin

setState(changes) method

Update the component's state by merging the specified changes on top of the existing state. If the component is connected to the document, and the new state has changed, this returns a promise to asynchronously render the component. Otherwise, this returns a resolved promise.

Parameters:

  • changes: PlainObjectthe changes to apply to the element's state

Returns: Promise - resolves when the new state has been rendered

Defined by ReactiveMixin

state property

The component's current state.

The returned state object is immutable. To update it, invoke internal.setState.

It's extremely useful to be able to inspect component state while debugging. If you append ?elixdebug=true to a page's URL, then ReactiveMixin will conditionally expose a public state property that returns the component's state. You can then access the state in your browser's debug console.

Type: PlainObject

Defined by ReactiveMixin

stateEffects(state, changed) method

Ask the component whether a state with a set of recently-changed fields implies that additional second-order changes should be applied to that state to make it consistent.

This method is invoked during a call to internal.setState to give all of a component's mixins and classes a chance to respond to changes in state. If one mixin/class updates state that it controls, another mixin/class may want to respond by updating some other state member that it controls.

This method should return a dictionary of changes that should be applied to the state. If the dictionary object is not empty, the internal.setState method will apply the changes to the state, and invoke this stateEffects method again to determine whether there are any third-order effects that should be applied. This process repeats until all mixins/classes report that they have no additional changes to make.

See an example of how ReactiveMixin invokes the stateEffects to ensure state consistency.

Parameters:

  • state: PlainObjecta proposal for a new state
  • changed: ChangedFlagsthe set of fields changed in this latest proposal for the new state

Returns: PlainObject

Defined by ReactiveMixin

template property

The template copied into the shadow tree of new instances of this element.

The default value of this property is a template that includes an instance the standard element being wrapped, with a <slot> element inside that to pick up the element's light DOM content. For example, if you wrap an <a> element, then the default template will look like:

<template>
  <style>
  :host {
    display: inline-block;
  }
  </style>
  <a id="inner">
    <slot></slot>
  </a>
</template>

The display styling applied to the host will be block for elements that are block elements by default, and inline-block (not inline) for other elements.

If you'd like the template to include other elements, then override this property and return a template of your own. The template should include an instance of the standard HTML element you are wrapping, and the ID of that element should be "inner".

Type: string|HTMLTemplateElement

Defined by WrappedStandardElement

wrap(extendsTag) static method

Creates a class that wraps a standard HTML element.

Note that the resulting class is a subclass of WrappedStandardElement, not the standard class being wrapped. E.g., if you call WrappedStandardElement.wrap('a'), you will get a class whose shadow tree will include an anchor element, but the class will not inherit from HTMLAnchorElement.

Parameters:

  • extendsTag: stringthe standard HTML element tag to extend

Defined by WrappedStandardElement