diff --git a/src/components/tabs/README.md b/src/components/tabs/README.md index 4d3659d6a4a..6434c940ec8 100644 --- a/src/components/tabs/README.md +++ b/src/components/tabs/README.md @@ -1,39 +1,40 @@ # Tabs -> Create tabbable panes of _local content_. The tabs component is built upon navs and cards -> internally. +> Create a widget of tabbable panes of _local content_. The tabs component is built upon navs and cards +> internally, and provides full keyboard navigation control of the tabs. -For navigation based tabs, use the [``](/docs/components/nav) component and -[``](/docs/components/card) component instead. +For navigation based tabs (i.e. tabs that would change the URL), use the +[``](/docs/components/nav) component instead. ## Basic usage ```html -
I'm the first fading tab -
I'm the second tab content -
Disabled tab! +

I'm the first fading tab

 +

I'm the second tab content

 +

Disabled tab!

 ``` **Tip:** You should supply each child `` component a unique `key` value if dynamically -adding, removing, showing, or hiding `` components. The `key` attribute is a special Vue -attribute, see https://vuejs.org/v2/api/#key). +adding or removing `` components (i.e. `v-if` or for loops). The `key` attribute is a +special Vue attribute, see https://vuejs.org/v2/api/#key). + ## Cards Integration Tabs support integrating with bootstrap cards. Just add the `card` property to ``. and place -it inside a `` component. Note that you should add `no-body` prop on `` component in -order to propertly decorate the card header and remove the extra padding introduced by `card-body`. +it inside a `` component. Note that you should add `no-body` prop on the `` component +in order to propertly decorate the card header and remove the extra padding introduced by `card-body`. ```html - Tab Contents 1 - Tab Contents 2 + Tab Contents 1 + Tab Contents 2 @@ -47,19 +48,19 @@ When `` is in `card` mode, each `` sub-component will automatical ```html - + Picture 1 footer - + Picture 2 footer - + Picture 3 footer - +
This tab does not have the no-body prop set
Quis magna Lorem anim amet ipsum do mollit sit cillum voluptate ex nulla tempor. Laborum consequat non elit enim exercitation cillum aliqua consequat id aliqua. Esse ex consectetur @@ -72,9 +73,10 @@ When `` is in `card` mode, each `` sub-component will automatical ``` -Setting the `no-body` prop on `` will have no affect when `` is not in `card` mode +**Note:** Setting the `no-body` prop on `` will have no affect when `` is not in `card` mode (as the `card-body` class is only set when in `card` mode). + ## Pills variant Tabs use the `tabs` styling by default. Just add `pills` property to `` for the pill style @@ -83,8 +85,8 @@ variant. ```html - Tab Contents 1 - Tab Contents 2 + Tab Contents 1 + Tab Contents 2 @@ -98,8 +100,8 @@ Visually move the tab controls to the bottom by setting the prop `end` ```html - Tab Contents 1 - Tab Contents 2 + Tab Contents 1 + Tab Contents 2 @@ -125,9 +127,9 @@ tabs work with or without `card` mode enabled. ```html - Tab Contents 1 - Tab Contents 2 - Tab Contents 3 + Tab Contents 1 + Tab Contents 2 + Tab Contents 3 @@ -139,9 +141,9 @@ Visually move the tab controls to the right hand side by setting the `end` prop: ```html - Tab Contents 1 - Tab Contents 2 - Tab Contents 3 + Tab Contents 1 + Tab Contents 2 + Tab Contents 3 @@ -156,9 +158,9 @@ column classes such as `col-2`, `col-3`, etc. ```html - Tab Contents 1 - Tab Contents 2 - Tab Contents 3 + Tab Contents 1 + Tab Contents 2 + Tab Contents 3 @@ -174,9 +176,7 @@ additional custom styling._ ## Fade animation -Fade is enabled by default when changing tabs. It can disabled with `no-fade` property. Note you -should use the `` component when adding contentless-tabs to maintain correct sizing and -alignment. See the advanced usage examples below for an example. +Fade is enabled by default when changing tabs. It can disabled with `no-fade` property. ## Add Tabs without content @@ -193,32 +193,45 @@ If you want to add extra tabs that do not have any content, you can put them in ``` +**Note:** extra (contentless) tabs should be a `` or have the class `nav-item` +with a root element of `
  • ` for proper rendering. + + ## Add custom content to tab title -If you want to add custom content to tab title, like HTML code, icons, or another Vue component, -this possible by using `title` slot +If you want to add custom content to tab title, like HTML code, icons, or another +non-interactive Vue component, this possible by using `title` slot ```html - - + + +

    Tab Contents 1

    +     + - Tab Contents 1 +

    Tab Contents 2

         ``` +**Do not** place interactive elements/components inside the title slot. The tab button is a +link which does not support child interactive elements per the HTML5 spec. + + ## Apply custom classes to the generated nav-tabs or pills -The tab selectors are based on Boostrap V4's `nav` markup ( i.e. -`ul.nav > li.nav-item > a.nav-link`). In some situations, you may want to add classes to the `
  • ` -(nav-item) and/or the `` (nav-link) on a per tab basis. To do so, simply supply the classname to -the `title-item-class` prop (for the `
  • ` element) or `title-link-class` prop (for the `` -element). Value's can be passed as a string or array of strings. +The tab selectors are based on Boostrap V4's `nav` markup ( i.e. `ul.nav > li.nav-item > a.nav-link`). +In some situations, you may want to add classes to the `
  • ` (nav-item) and/or the `` (nav-link) +on a per tab basis. To do so, simply supply the classname to the `title-item-class` prop (for the +`
  • ` element) or `title-link-class` prop (for the `` element). Value's can be passed as a string +or array of strings. **Note:** _The `active` class is automatically applied to the active tabs `` element. You may need to accomodate your custom classes for this._ @@ -227,9 +240,9 @@ need to accomodate your custom classes for this._ @@ -258,31 +271,48 @@ need to accomodate your custom classes for this._ ## Keyboard Navigation -Keyboard navigation is enabled by default. +Keyboard navigation is enabled by default for ARIA compliance with tablists when +a tab button has focus. + +| Keypress | Action | +| --------------------------------------------------------------------- | ---------------------------------------------- | +| LEFT or UP | Activate the previous non-disabled tab | +| RIGHT or DOWN | Activate the next non-disabled tab | +| SHIFT+LEFT or SHIFT+UP | Activate the first non-disabled tab | +| HOME | Activate the first non-disabled tab | +| SHIFT+RIGHT or SHIFT+DOWN | Activate the last non-disabled tab | +| END | Activate the last non-disabled tab | +| TAB | Move focus to the active tab content | +| SHIFT+TAB | Move focus to the previous control on the page | + +Disable keyboard navigation by setting the prop `no-key-nav`. Behavior will now default to +regular browser navigation with TAB key. + +| Keypress | Action | +| ------------------------------- | ------------------------------------------------------ | +| TAB | Move to the next tab button or control on the page | +| SHIFT+TAB | Move to the previous tab button or control on the page | +| ENTER | Activate current focused button's tab | + + +## Programatically activating and deactivating tabs -| Keypress | Action | -| --------------------------------------------------------------------- | ---------------------------------------- | -| LEFT or UP | Move to the previous non-disabled tab | -| RIGHT or DOWN | Move to the next non-disabled tab | -| SHIFT+LEFT or SHIFT+UP | Move to the first non-disabled tab | -| SHIFT+RIGHT or SHIFT+DOWN | Move to the last non-disabled tab | -| TAB | Move to the next control on the page | -| SHIFT+TAB | Move to the previous control on the page | +Use the `` v-model to control which tab is active by setting the v-model to +the index (zero-based) of the tab to be shown (see example below). -Disable it by setting the prop `no-key-nav`. Behavior will now default to standard browser -navigation with TAB key. +Alternatively, you can use the `active` prop on each `` with the `.sync` modifier +to activate the tab, or to detect if a particular tab is active. -| Keypress | Action | -| ------------------------------- | ----------------------------------------------- | -| TAB | Move to the next tab or control on the page | -| SHIFT+TAB | Move to the previous tab or control on the page | +Each `` instance also provides two public methods to activate or deactivate +the tab. The methods are `.activate()` and `.deactivate()`, respectively. If activation +or deactivaton fails (i.e. a tab is disabled or no tab is available to move activation +to), then the currently active tab will remain active and the method will return `false`. +You will need a reference to the `` in order to use these methods. -**Caution:** If you have text or text-like inputs in your tabs, leave keyboard navigation off, as it -is not possble to use key presses to jump out of a text (or test-like) inputs. ## Advanced Examples -### External controls +### External controls using v-model ```html