UNPKG

@material/tabs/README.md

Version:
26.9 kBMarkdownView Raw
1<!--docs:
2title: "Tabs (Deprecated)"
3layout: detail
4section: components
5excerpt: "A tabbed navigation component."
6iconId: tabs
7path: /catalog/tabs/legacy/
8-->
9
10## Important - Deprecation Notice
11
12The `mdc-tabs` package is deprecated and no longer maintained, and is no longer included in the all-in-one
13`material-components-web` package. Improved functionality is available across the `mdc-tab-bar`, `mdc-tab-scroller`,
14`mdc-tab-indicator`, and `mdc-tab` packages, which are now included in the `material-components-web` package.
15Bugs and feature requests will no longer be accepted for this package. It is recommended that you migrate to the new
16packages to continue to receive new features and updates.
17
18# MDC Tabs
19
20The MDC Tabs component contains components which are used to create spec-aligned tabbed navigation components adhering to the
21[Material Design tabs guidelines](https://material.io/go/design-tabs). These components are:
22
23- **mdc-tab**: The individual tab elements
24- **mdc-tab-bar**: The main component which is composed of `mdc-tab` elements
25- **mdc-tab-bar-scroller**: The component which controls the horizontal scrolling behavior of an `mdc-tab-bar` that overflows its container
26
27## Design & API Documentation
28
29<ul class="icon-list">
30  <li class="icon-list-item icon-list-item--spec">
31    <a href="https://material.io/go/design-tabs">Material Design guidelines: Tabs</a>
32  </li>
33  <li class="icon-list-item icon-list-item--link">
34    <a href="https://material-components.github.io/material-components-web-catalog/#/component/tabs">Demo</a>
35  </li>
36</ul>
37
38## Installation
39
40```
41npm install @material/tabs
42```
43
44## Tabs usage
45
46`mdc-tab-bar` can be used as a CSS only component, or a more dynamic JavaScript
47component.
48
49There are also three different permutations of tab labels. These include text,
50icon-only, and text with icon. An example of each is available on the demo site.
51
52### Icons
53
54We recommend using [Material Icons](https://material.io/tools/icons/) from Google Fonts:
55
56```html
57<head>
58  <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
59</head>
60```
61
62However, you can also use SVG, [Font Awesome](https://fontawesome.com/), or any other icon library you wish.
63
64#### Tab Bar with text labels
65
66```html
67<nav id="basic-tab-bar" class="mdc-tab-bar">
68  <a class="mdc-tab mdc-tab--active" href="#one">Home</a>
69  <a class="mdc-tab" href="#two">Merchandise</a>
70  <a class="mdc-tab" href="#three">About Us</a>
71  <span class="mdc-tab-bar__indicator"></span>
72</nav>
73```
74
75#### Tab Bar with icon labels
76
77```html
78<nav class="mdc-tab-bar mdc-tab-bar--icon-tab-bar">
79  <a class="mdc-tab mdc-tab--active" href="#recents">
80    <i class="material-icons mdc-tab__icon" aria-label="Recents">phone</i>
81  </a>
82  <a class="mdc-tab" href="#favorites">
83    <i class="material-icons mdc-tab__icon" aria-label="Favorites">favorite</i>
84  </a>
85  <a class="mdc-tab" href="#nearby">
86    <i class="material-icons mdc-tab__icon" aria-label="nearby">person_pin</i>
87  </a>
88  <span class="mdc-tab-bar__indicator"></span>
89</nav>
90```
91
92#### Tab Bar with icon and text labels
93
94```html
95<nav id="icon-text-tab-bar" class="mdc-tab-bar mdc-tab-bar--icons-with-text">
96  <a class="mdc-tab mdc-tab--with-icon-and-text mdc-tab--active" href="#recents">
97    <i class="material-icons mdc-tab__icon" aria-hidden="true">phone</i>
98    <span class="mdc-tab__icon-text">Recents</span>
99  </a>
100  <a class="mdc-tab mdc-tab--with-icon-and-text" href="#favorites">
101    <i class="material-icons mdc-tab__icon" aria-hidden="true">favorite</i>
102    <span class="mdc-tab__icon-text">Favorites</span>
103  </a>
104  <a class="mdc-tab mdc-tab--with-icon-and-text" href="#nearby">
105    <i class="material-icons mdc-tab__icon" aria-hidden="true">person_pin</i>
106    <span class="mdc-tab__icon-text">Nearby</span>
107  </a>
108  <span class="mdc-tab-bar__indicator"></span>
109</nav>
110```
111
112#### CSS Only Support
113
114In order for the indicator to appear, you will need to change your mark up if you are using CSS Only. Each `.mdc-tab` will have a child element with the class `.mdc-tab__indicator` as shown below:
115
116```html
117<nav id="basic-tab-bar" class="mdc-tab-bar">
118  <a class="mdc-tab mdc-tab--active" href="#one">
119    Home
120    <span class="mdc-tab__indicator"></span>
121  </a>
122  <a class="mdc-tab" href="#two">
123    Merchandise
124    <span class="mdc-tab__indicator"></span>
125  </a>
126  <a class="mdc-tab" href="#three">
127    About Us
128    <span class="mdc-tab__indicator"></span>
129  </a>
130</nav>
131```
132
133#### RTL Support
134
135Tab Bars will reverse the order of their tabs if they are placed within an
136ancestor element with attribute `dir="rtl"`.
137
138```html
139<html dir="rtl">
140  <!--...-->
141  <nav id="basic-tab-bar" class="mdc-tab-bar">
142    <a class="mdc-tab mdc-tab--active" href="#one">Home</a>
143    <a class="mdc-tab" href="#two">Merchandise</a>
144    <a class="mdc-tab" href="#three">About Us</a>
145    <span class="mdc-tab-bar__indicator"></span>
146  </nav>
147</html>
148```
149
150### Dynamic view switching
151
152While facilitating the view switching is left up to the developer, the demo site
153provides a minimal example of how to do so using JavaScript, also shown below.
154
155#### Markup:
156```html
157<section id="dynamic-demo-toolbar">
158  <nav id="dynamic-tab-bar" class="mdc-tab-bar" role="tablist">
159    <a role="tab" aria-controls="panel-1"
160       class="mdc-tab mdc-tab--active" href="#panel-1">Item One</a>
161    <a role="tab" aria-controls="panel-2"
162       class="mdc-tab" href="#panel-2">Item Two</a>
163    <a role="tab" aria-controls="panel-3"
164       class="mdc-tab" href="#panel-3">Item Three</a>
165    <span class="mdc-tab-bar__indicator"></span>
166  </nav>
167</section>
168<section>
169  <div class="panels">
170    <p class="panel active" id="panel-1" role="tabpanel" aria-hidden="false">Item One</p>
171    <p class="panel" id="panel-2" role="tabpanel" aria-hidden="true">Item Two</p>
172    <p class="panel" id="panel-3" role="tabpanel" aria-hidden="true">Item Three</p>
173  </div>
174  <div class="dots">
175    <a class="dot active" data-trigger="panel-1" href="#panel-1"></a>
176    <a class="dot" data-trigger="panel-2" href="#panel-2"></a>
177    <a class="dot" data-trigger="panel-3" href="#panel-3"></a>
178  </div>
179</section>
180```
181
182#### Script:
183
184```js
185var dynamicTabBar = window.dynamicTabBar = new mdc.tabs.MDCTabBar(document.querySelector('#dynamic-tab-bar'));
186var dots = document.querySelector('.dots');
187var panels = document.querySelector('.panels');
188
189dynamicTabBar.tabs.forEach(function(tab) {
190  tab.preventDefaultOnClick = true;
191});
192
193function updateDot(index) {
194  var activeDot = dots.querySelector('.dot.active');
195  if (activeDot) {
196    activeDot.classList.remove('active');
197  }
198  var newActiveDot = dots.querySelector('.dot:nth-child(' + (index + 1) + ')');
199  if (newActiveDot) {
200    newActiveDot.classList.add('active');
201  }
202}
203
204function updatePanel(index) {
205  var activePanel = panels.querySelector('.panel.active');
206  if (activePanel) {
207    activePanel.classList.remove('active');
208  }
209  var newActivePanel = panels.querySelector('.panel:nth-child(' + (index + 1) + ')');
210  if (newActivePanel) {
211    newActivePanel.classList.add('active');
212  }
213}
214
215dynamicTabBar.listen('MDCTabBar:change', function ({detail: tabs}) {
216  var nthChildIndex = tabs.activeTabIndex;
217
218  updatePanel(nthChildIndex);
219  updateDot(nthChildIndex);
220});
221
222dots.addEventListener('click', function (evt) {
223  if (!evt.target.classList.contains('dot')) {
224    return;
225  }
226
227  evt.preventDefault();
228
229  var dotIndex = [].slice.call(dots.querySelectorAll('.dot')).indexOf(evt.target);
230
231  if (dotIndex >= 0) {
232    dynamicTabBar.activeTabIndex = dotIndex;
233  }
234
235  updatePanel(dotIndex);
236  updateDot(dotIndex);
237})
238```
239
240### Sass Mixins
241
242To customize the ink color of any part of the tab, use the following mixins. We recommend you apply these mixins within CSS selectors like `.foo-tab:not(.mdc-tab--active)` to select your inactive tabs, `foo-tab:hover` to select the hover state of your tabs, and `.foo-tab.mdc-tab--active` to select your active tabs.
243
244#### `mdc-tab-ink-color`
245
246Use this mixin to set the color of all ink on the tab.
247
248#### `mdc-tab-icon-ink-color`
249
250This mixin customizes the icon ink color.
251
252#### `mdc-tab-label-ink-color`
253
254This mixin customizes the label ink color.
255
256#### `mdc-tab-bar-indicator-ink-color`
257
258This mixin customizes the indicator ink color.
259
260### Using the CSS-Only Component
261
262`mdc-tab-bar` ships with css for styling a tab layout according to the Material
263Design spec. To use CSS only tab bars, simply use the available class names.
264Note the available `mdc-tab--active` modifier class. This is used to denote the
265currently active tab.
266
267```html
268<nav class="mdc-tab-bar">
269  <a class="mdc-tab mdc-tab--active" href="#one">Item One</a>
270  <a class="mdc-tab" href="#two">Item Two</a>
271  <a class="mdc-tab" href="#three">Three</a>
272  <span class="mdc-tab-bar__indicator"></span>
273</nav>
274```
275
276### Using the JavaScript Component
277
278`mdc-tab-bar` ships with a Component/Foundation combo for ingesting instances of `mdc-tab` (a tab).
279`mdc-tab-bar` uses its `initialize()` method call a factory function which gathers and instantiates
280any tab elements that are children of the `mdc-tab-bar` root element.
281
282#### Including in code
283
284##### ES Modules
285
286```javascript
287import {MDCTab, MDCTabFoundation} from '@material/tabs';
288import {MDCTabBar, MDCTabBarFoundation} from '@material/tabs';
289```
290
291##### CommonJS
292
293```javascript
294const mdcTabs = require('@material/tabs');
295const MDCTab = mdcTabs.MDCTab;
296const MDCTabFoundation = mdcTabs.MDCTabFoundation;
297
298const MDCTabBar = mdcTabs.MDCTabBar;
299const MDCTabBarFoundation = mdcTabs.MDCTabBarFoundation;
300```
301
302##### AMD
303
304```javascript
305require(['path/to/@material/tabs'], mdcTabs => {
306  const MDCTab = mdcTabs.MDCTab;
307  const MDCTabFoundation = mdcTabs.MDCTabFoundation;
308
309  const MDCTabBar = mdcTabs.MDCTabBar;
310  const MDCTabBarFoundation = mdcTabs.MDCTabBarFoundation;
311});
312```
313
314##### Global
315
316```javascript
317const MDCTab = mdc.tabs.MDCTab;
318const MDCTabFoundation = mdc.tabs.MDCTabFoundation;
319
320const MDCTabBar = mdc.tabs.MDCTabBar;
321const MDCTabBarFoundation = mdc.tabs.MDCTabBarFoundation;
322```
323
324#### Automatic Instantiation
325
326If you do not care about retaining the component instance for the tabs, simply
327call `attachTo()` and pass it a DOM element.
328
329```javascript
330mdc.tabs.MDCTabBar.attachTo(document.querySelector('#my-mdc-tab-bar'));
331```
332
333#### Manual Instantiation
334
335Tabs can easily be initialized using their default constructors as well, similar
336to `attachTo`. This process involves a factory to create an instance of MDCTab
337from each tab Element inside of the `mdc-tab-bar` node during the initialization phase
338of `MDCTabBar`, e.g.:
339
340```html
341<nav id="my-mdc-tab-bar" class="mdc-tab-bar">
342  <a class="mdc-tab mdc-tab--active" href="#one">Item One</a>
343  <a class="mdc-tab" href="#two">Item Two</a>
344  <a class="mdc-tab" href="#three">Three</a>
345  <span class="mdc-tab-bar__indicator"></span>
346</nav>
347```
348
349```javascript
350import {MDCTabBar, MDCTabBarFoundation} from '@material/tabs';
351
352const tabBar = new MDCTabBar(document.querySelector('#my-mdc-tab-bar'));
353```
354
355### Using the JavaScript Tab Bar Scroller Component
356
357`mdc-tab-bar-scroller` ships with a Component/Foundation combo which wraps instances of `mdc-tab-bar`. `mdc-tab-bar-scroller` uses its `initialize()` method call a factory function which gathers and instantiates any tab bar elements that are children of the `mdc-tab-bar-scroller` root element.
358
359The anatomy of `mdc-tab-bar-scroller` includes an instance of `mdc-tab-bar`, RTL-aware forward and back indicators which, when actioned on, move the tab bar left and right, and a scroll frame. The scroll frame is the parent element of the tab bar, and serves to mask the tabs in the tab bar when they overflow the available width.
360
361#### Including in code
362
363##### ES Module syntax
364
365```javascript
366import {MDCTab, MDCTabFoundation} from '@material/tabs';
367import {MDCTabBar, MDCTabBarFoundation} from '@material/tabs';
368import {MDCTabBarScroller, MDCTabBarFoundationScroller} from '@material/tabs';
369```
370
371##### CommonJS
372
373```javascript
374const mdcTabs = require('@material/tabs');
375const MDCTab = mdcTabs.MDCTab;
376const MDCTabFoundation = mdcTabs.MDCTabFoundation;
377
378const MDCTabBar = mdcTabs.MDCTabBar;
379const MDCTabBarFoundation = mdcTabs.MDCTabBarFoundation;
380
381const MDCTabBarScroller = mdcTabs.MDCTabBarScroller;
382const MDCTabBarScrollerFoundation = mdcTabs.MDCTabBarScrollerFoundation;
383```
384
385##### AMD
386
387```javascript
388require(['path/to/@material/tabs'], mdcTabs => {
389  const MDCTab = mdcTabs.MDCTab;
390  const MDCTabFoundation = mdcTabs.MDCTabFoundation;
391
392  const MDCTabBar = mdcTabs.MDCTabBar;
393  const MDCTabBarFoundation = mdcTabs.MDCTabBarFoundation;
394
395  const MDCTabBarScroller = mdcTabs.MDCTabBarScroller;
396  const MDCTabBarScrollerFoundation = mdcTabs.MDCTabBarScrollerFoundation;
397});
398```
399
400##### Global
401
402```javascript
403const MDCTab = mdc.tabs.MDCTab;
404const MDCTabFoundation = mdc.tabs.MDCTabFoundation;
405
406const MDCTabBar = mdc.tabs.MDCTabBar;
407const MDCTabBarFoundation = mdc.tabs.MDCTabBarFoundation;
408
409const MDCTabBarScroller = mdc.tabs.MDCTabBarScroller;
410const MDCTabBarScrollerFoundation = mdc.tabs.MDCTabBarScrollerFoundation;
411```
412
413#### Automatic Instantiation
414
415If you do not care about retaining the component instance for the tabs, simply
416call `attachTo()` and pass it a DOM element.
417
418```javascript
419mdc.tabs.MDCTabBarScroller.attachTo(document.querySelector('#my-mdc-tab-bar-scroller'));
420```
421
422#### Manual Instantiation
423
424Tab Bar Scrollers can easily be initialized using their default constructors as well, similar
425to `attachTo`. This process involves a factory to create an instance of `MDCTabBar`
426from the `mdc-tab-bar` Element inside of the `mdc-tab-bar-scroller` node during the initialization phase
427of `MDCTabBarScroller`, e.g.:
428
429```html
430<div id="my-mdc-tab-bar-scroller" class="mdc-tab-bar-scroller">
431  <div class="mdc-tab-bar-scroller__indicator mdc-tab-bar-scroller__indicator--back">
432    <a class="mdc-tab-bar-scroller__indicator__inner material-icons" href="#" aria-label="scroll back button">
433      navigate_before
434    </a>
435  </div>
436  <div class="mdc-tab-bar-scroller__scroll-frame">
437    <nav id="my-scrollable-tab-bar" class="mdc-tab-bar mdc-tab-bar-scroller__scroll-frame__tabs">
438      <a class="mdc-tab mdc-tab--active" href="#one">Item One</a>
439      <a class="mdc-tab" href="#two">Item Two</a>
440      <a class="mdc-tab" href="#three">Item Three</a>
441      <a class="mdc-tab" href="#four">Item Four</a>
442      <a class="mdc-tab" href="#five">Item Five</a>
443      <a class="mdc-tab" href="#six">Item Six</a>
444      <a class="mdc-tab" href="#seven">Item Seven</a>
445      <a class="mdc-tab" href="#eight">Item Eight</a>
446      <a class="mdc-tab" href="#nine">Item Nine</a>
447      <span class="mdc-tab-bar__indicator"></span>
448    </nav>
449  </div>
450  <div class="mdc-tab-bar-scroller__indicator mdc-tab-bar-scroller__indicator--forward">
451    <a class="mdc-tab-bar-scroller__indicator__inner material-icons" href="#" aria-label="scroll forward button">
452      navigate_next
453    </a>
454  </div>
455</div>
456```
457
458```javascript
459import {MDCTabBarScroller, MDCTabBarScrollerFoundation} from '@material/tabs';
460
461const tabBarScroller = new MDCTabBarScroller(document.querySelector('#my-mdc-tab-bar-scroller'));
462```
463
464Tab Bar Scrollers can also instantiate any `mdc-tab-bar` from a DOM element on the fly using a built in factory function:
465
466```js
467import {MDCTabBarScroller, MDCTabBarScrollerFoundation} from '@material/tabs';
468
469const tabBarEl = document.querySelector('#my-mdc-tab-bar');
470const scrollerEl = document.querySelector('#my-mdc-tab-bar-scroller');
471
472const tabBarScroller = new MDCTabBarScroller(scrollerEl, undefined, tabBarEl);
473```
474
475This will create an instance of MDC Tab Bar during the initialization phase of Tab Bar Scroller.
476
477## Tab
478
479### Tab component API
480
481#### Properties
482
483| Property Name | Type | Description |
484| --- | --- | --- |
485| `computedWidth` | `number` | _(read-only)_ The width of the tab. |
486| `computedLeft` | `number` | _(read-only)_ The left offset of the tab. |
487| `isActive` | `boolean` | Whether or not the tab is active. Setting this makes the tab active. |
488| `preventDefaultOnClick` | `boolean` | Whether or not the tab will call `preventDefault()` on an event. Setting this makes the tab call `preventDefault()` on events. |
489
490### Tab Events
491
492#### MDCTab:selected
493
494Broadcast when a user actions on the tab.
495
496### Using the Foundation Class
497
498MDC Tab ships with an `MDCTabFoundation` class that external frameworks and libraries can
499use to integrate the component. As with all foundation classes, an adapter object must be provided.
500
501### Adapter API
502
503| Method Signature | Description |
504| --- | --- |
505| `addClass(className: string) => void` | Adds a class to the root element. |
506| `removeClass(className: string) => void` | Removes a class from the root element. |
507| `registerInteractionHandler(evt: string, handler: EventListener) => void` | Adds an event listener to the root element, for the specified event name. |
508| `deregisterInteractionHandler(evt: string, handler: EventListener) => void` | Removes an event listener from the root element, for the specified event name. |
509| `getOffsetWidth() => number` | Return the width of the tab |
510| `getOffsetLeft() => number` | Return distance between left edge of tab and left edge of its parent element |
511| `notifySelected() => {}` | Broadcasts an event denoting that the user has actioned on the tab |
512
513### The full foundation API
514
515#### MDCTabFoundation.getComputedWidth() => number
516
517Return the computed width for tab.
518
519#### MDCTabFoundation.getComputedLeft() => number
520
521Return the computed left offset for tab.
522
523#### MDCTabFoundation.isActive() => boolean
524
525Return true if tab is active.
526
527#### MDCTabFoundation.setActive(isActive = false) => void
528
529Set tab to active. If `isActive` is true, adds the active modifier class, otherwise removes it.
530
531#### MDCTabFoundation.preventsDefaultOnClick() => boolean
532
533Return true if the tab prevents the default click action
534
535#### MDCTabFoundation.setPreventDefaultOnClick(preventDefaultOnClick = false) => void
536
537Sets tabs `preventDefaultOnClick` property to the value of the `preventDefaultOnClick` argument passed.
538
539#### MDCTabFoundation.measureSelf() => void
540
541Sets `computedWidth_` and `computedLeft_` for a tab.
542
543## Tab Bar
544
545### Tab Bar component API
546
547#### Properties
548
549| Property Name | Type | Description |
550| --- | --- | --- |
551| `tabs` | `MDCTab[]` | _(read-only)_ An array of the tab bar's instances of MDC Tab. |
552| `activeTab` | `MDCTab` | The currently active tab. Setting this makes the tab active. |
553| `activeTabIndex` | `number` | The index of the currently active tab. Setting this makes the tab at the given index active. |
554
555#### MDCTabBar.layout() => void
556
557Proxies to the foundation's `layout()` method.
558
559### Tab Bar Events
560
561#### MDCTabBar:change
562
563Broadcast when a user actions on a tab, resulting in a change in the selected tab.
564
565### Using the Foundation Class
566
567`mdc-tab-bar` ships with an `MDCTabBarFoundation` class that external frameworks
568and libraries can use to integrate the component. As with all foundation
569classes, an adapter object must be provided.
570
571### Adapter API
572
573| Method Signature | Description |
574| --- | --- |
575| `addClass(className: string) => void` | Adds a class to the root element. |
576| `removeClass(className: string) => void` | Removes a class from the root element. |
577| `bindOnMDCTabSelectedEvent() => void` | Adds `MDCTab:selected` event listener to root |
578| `unbindOnMDCTabSelectedEvent() => void` | Removes `MDCTab:selected` event listener from root |
579| `registerResizeHandler(handler: EventListener) => void` | Adds an event listener to the root element, for a resize event. |
580| `deregisterResizeHandler(handler: EventListener) => void` | Removes an event listener from the root element, for a resize event. |
581| `getOffsetWidth() => number` | Returns width of root element. |
582| `setStyleForIndicator(propertyName: string, value: string) => void` | Sets style property for indicator. |
583| `getOffsetWidthForIndicator() => number` | Returns width of indicator. |
584| `notifyChange(evtData: Object) => void` | Emits `MDCTabBar:change` event, passes evtData. |
585| `getNumberOfTabs() => number` | Returns number of tabs in MDC Tabs instance. |
586| `getActiveTab() => MDCTab` | Returns the instance of MDCTab that is currently active. |
587| `isTabActiveAtIndex(index: number) => boolean` | Returns true if tab at index is active. |
588| `setTabActiveAtIndex(index: number) => void` | Sets tab active at given index. |
589| `isDefaultPreventedOnClickForTabAtIndex(index: number) => boolean` | Returns true if tab does not prevent default click action. |
590| `setPreventDefaultOnClickForTabAtIndex(index: number, preventDefaultOnClick: boolean)` | Sets preventDefaultOnClick for tab at given index |
591| `measureTabAtIndex(index: number) => void` | sets measurements (width, left offset) for tab at given index. |
592| `getComputedWidthForTabAtIndex(index: number) => number` | Returns width of tab at given index. |
593| `getComputedLeftForTabAtIndex(index: number) => number` | Returns left offset of tab at given index. |
594
595### The full foundation API
596
597#### MDCTabBarFoundation.layout() => void
598
599Sets layout for the Tab Bar component.
600
601#### MDCTabBarFoundation.getActiveTabIndex() => number
602
603Returns index of currently active tab
604
605#### MDCTabBarFoundation.getComputedWidth() => number
606
607Returns the width of the element containing the tabs.
608
609#### MDCTabBarFoundation.switchToTabAtIndex(index, shouldNotify) => void
610
611Updates the active tab to be the tab at the given index, emits `MDCTabBar:change` if `shouldNotify` is true.
612
613#### MDCTabBarFoundation.getActiveTabIndex() => number
614
615Returns the index of the currently active tab.
616
617## Tab Bar Scroller
618
619### Tab Bar Scroller component API
620
621#### Properties
622
623| Property Name | Type | Description |
624| --- | --- | --- |
625| `tabBar` | `MDCTabBar` | _(read-only)_ The scroller's tab bar. |
626
627#### MDCTabBarScroller.layout() => void
628
629Proxies to the foundation's `layout()` method.
630
631### Using the Foundation Class
632
633MDC Tab Bar Scroller ships with an `MDCTabBarScrollerFoundation` class that external frameworks and libraries can use to integrate the component. As with all foundation classes, an adapter object must be provided.
634
635### Adapter API
636
637| Method Signature | Description |
638| --- | --- |
639| `addClass(className: string) => void` | Adds a class to the root element. |
640| `removeClass(className: string) => void` | Removes a class from the root element. |
641| `eventTargetHasClass(target: HTMLElement, className: string) => boolean` | Returns true if target has a given class name |
642| `addClassToForwardIndicator(className: string) => void` | Adds a given class to the forward indicator |
643| `removeClassFromForwardIndicator(className: string) => void` | Removes a given class from the forward indicator |
644| `addClassToBackIndicator(className: string) => void` | Adds a given class to the back indicator |
645| `removeClassFromBackIndicator(className: string) => void` | Removes a given class from the back indicator |
646| `isRTL() => boolean` | Returns true if in RTL context. False otherwise. |
647| `registerBackIndicatorClickHandler(handler: EventListener) => void` | Registers an event handler to be called when a `click` event happens on the back indicator |
648| `deregisterBackIndicatorClickHandler(handler: EventHandler) => void` | Deregisters an event handler from a `click` event happening on the back indicator |
649| `registerForwardIndicatorClickHandler(handler: EventHandler) => void` | Registers an event handler to be called when a `click` event happens on the forward indicator |
650| `deregisterForwardIndicatorClickHandler(handler: EventHandler) => void` | Deregisters an event handler from a `click` event happening on the forward indicator. |
651| `registerCapturedInteractionHandler(evt: string, handler: EventHandler) => void` | Registers an event handler to be called when a `focus`, `touchstart`, or `mousedown` event happens on the root of the component. These events gets dispatched to the listener during the capture phase. They also govern the scrolling behavior when tabs are tabbed to or actioned on. |
652| `deregisterCapturedInteractionHandler(evt: string, handler: EventHandler) => void` | Deregisters an event handler from a `focus`, `touchstart`, or `mousedown` events happening on the root of the component |
653| `registerWindowResizeHandler(handler: EventHandler) => void` | Registers an event handler to be called when a `resize` event happens on the `window` |
654| `deregisterWindowResizeHandler(handler: EventHandler) => void `| Deregisters an event handler from a `resize` event happening on the `window` |
655| `getNumberOfTabs() => number` | Returns the number of tabs in the scroller's tab bar |
656| `getComputedWidthForTabAtIndex(index: number) => number` | Returns the width of a tab at the given index |
657| `getComputedLeftForTabAtIndex(index: number) => number` | Returns the left offset of a tab at the given index |
658| `getOffsetWidthForScrollFrame() => number` | Returns the width of the scroll frame. This is the width of the visible tabs. |
659| `getScrollLeftForScrollFrame() => number` | Returns the `scrollLeft` value of the scroll frame |
660| `setScrollLeftForScrollFrame(scrollLeftAmount: number) => void` | Sets the value of `scrollLeft` for the scroll frame. |
661| `getOffsetWidthForTabBar() => number` | Returns the width of the _entire_ tab bar, including that which is occluded. |
662| `setTransformStyleForTabBar(value: string) => void` | Sets the `translateX` `transform` property for the tab bar. |
663| `getOffsetLeftForEventTarget(target: HTMLElement) => number`| Returns the left offset of a given element. |
664| `getOffsetWidthForEventTarget(target: HTMLElement) => number` | Returns the width of a given element. |
665
666### The full foundation API
667
668#### MDCTabBarScrollerFoundation.scrollBack() => void
669
670Scrolls the tab bar such that the leftmost tab traverses the scroll frame and becomes the rightmost tab, potentially being partially, but not fully, occluded.
671
672#### MDCTabBarScrollerFoundation.scrollForward() => void
673
674Scrolls the tab bar such that the rightmost tab traverses the scroll frame and becomes the leftmost tab. This tabs left offset will line up with the left edge of the scroll frame, and never be partially or fully occluded.
675
676> **NOTE:** Due to a quirk in event behavior, we allow the rightmost tab to be partially occluded even when tabbed to because clicking on such an element would shift the frame on the `focus` event. This would result in a scenario where the ripple persists and the intended tab would not be selected due to the tab bar shifting before the `mouseup` or `click` events get dispatched.
677
678#### MDCTabBarScrollerFoundation.scrollToTabAtIndex(index: number) => void
679
680Scrolls the tab bar such that the tab at the index provided traverses the scroll frame and becomes the leftmost tab.
681
682#### MDCTabBarScrollerFoundation.layout() => void
683
684If the tab bar is overflowing its available width, this method will reset the back and forward indicators to the correct states (visible/hidden) based on the new width.