Content switcher

Content switcher

Code:
<!--
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<div data-content-switcher class="bx--content-switcher" role="tablist" aria-label="Demo switch content">
  <button class="bx--content-switcher-btn bx--content-switcher--selected"
    data-target=".demo--panel--opt-1" role="tab"  aria-selected="true"  >
    <span class=bx--content-switcher__label>First section</span>
  </button>
  <button class="bx--content-switcher-btn"
    data-target=".demo--panel--opt-2" role="tab"  >
    <span class=bx--content-switcher__label>Second section</span>
  </button>
  <button class="bx--content-switcher-btn"
    data-target=".demo--panel--opt-3" role="tab"  >
    <span class=bx--content-switcher__label>Third section</span>
  </button>
</div>

Content switcher disabled

Code:
<!--
  Copyright IBM Corp. 2016, 2018

  This source code is licensed under the Apache-2.0 license found in the
  LICENSE file in the root directory of this source tree.
-->

<div data-content-switcher class="bx--content-switcher" role="tablist" aria-label="Demo switch content">
  <button class="bx--content-switcher-btn bx--content-switcher--selected"
    data-target=".demo--panel--opt-1" role="tab"  aria-selected="true"   disabled >
    <span class=bx--content-switcher__label>First section</span>
  </button>
  <button class="bx--content-switcher-btn"
    data-target=".demo--panel--opt-2" role="tab"   disabled >
    <span class=bx--content-switcher__label>Second section</span>
  </button>
  <button class="bx--content-switcher-btn"
    data-target=".demo--panel--opt-3" role="tab"   disabled >
    <span class=bx--content-switcher__label>Third section</span>
  </button>
</div>

Documentation

SCSS

Modifiers

Name Description
.bx--content-switcher--selected Applies the "selected" styles to the content-switcher button

Javascript

Getting component class reference

ES2015
import { ContentSwitcher } from 'carbon-components';
With pre-build bundle (carbon-components.min.js)
var ContentSwitcher = CarbonComponents.ContentSwitcher;

Instantiating

// `#my-content-switcher` is an element with `[data-content-switcher]` attribute
ContentSwitcher.create(document.getElementById('my-content-switcher'));

Public Methods

Name Params Description
setActive item: HTMLElement, callback: Function Uses data-target attribute to show a content panel using the given CSS selector. Non-active targets will be hidden. You can also pass in an optional callback function, see FAQ for details
release Deletes the instance and removes document event listeners
Example - Changing the active item
// `#my-content-switcher` is an element with `[data-content-switcher]` attribute
var contentSwitcherInstance = ContentSwitcher.create(
  document.getElementById('my-content-switcher')
);
// `#my-content-switcher-btn-1` is one of the `<button>`s with `bx--content-switcher-btn` class
contentSwitcherInstance.setActive(
  document.getElementById('my-content-switcher-btn-1')
);

Options

Option Default Selector Description
selectorInit [data-content-switcher] The CSS selector to find content-switcher
selectorButton input[type="radio"], .bx--content-switcher-btn The CSS selector to find the content-switcher buttons
classActive bx--content-switcher--selected The className for a selected button
eventBeforeSelected content-switcher-beingselected Custom event fired before a button is selected in content-switcher
eventAfterSelected content-switcher-selected Custom event fired after a button is selected in content-switcher

Events

Event Name Description
content-switcher-beingselected Custom event fired before a button is selected in content-switcher
content-switcher-selected Custom event fired after a button is selected in content-switcher
Example

Preventing a content switcher item from being selected in a certain condition

document.addEventListener('content-switcher-beingselected', function(evt) {
  if (!myApplication.shouldContentSwitcherItemBeSelected(evt.target)) {
    evt.preventDefault();
  }
});
Example

Notifying events of all content switcher items being selected to an analytics library

document.addEventListener('content-switcher-selected', function(evt) {
  myAnalyticsLibrary.send({
    action: 'Content switcher item selected',
    id: evt.target.id,
  });
});

Classes

Name Description
bx--content-switcher--selected The className for a selected button

FAQ

Preset an active button and panel with HTML

While SCSS and JS are setup, you can configure Content Switcher and its associated content through the HTML.

Each bx--content-switcher-btn has a data-target value with a selector for a panel element. When one of these buttons is clicked, then it will show the panel that the data-target is pointing to.

For example,

The first button has a data-target pointing to .demo-panel--opt-1. When clicking the first button, the JavaScript will find the DOM element using the given data-target selector and display it while hiding all other panels using the hidden attribute.

Below is an HTML setup for Content Switcher that will do the following:

  • Select the first button by default (as indicated by bx--content-switcher--selected class)
  • Show the <div class="demo--panel--opt-1"> element
  • Hide the other elements
<div data-content-switcher class="bx--content-switcher">
  <button
    class="bx--content-switcher-btn bx--content-switcher--selected"
    data-target=".demo--panel--opt-1"
  >
    Option 1
  </button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2">
    Option 2
  </button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3">
    Option 3
  </button>
</div>
<div class="demo--panel--opt-1">Show Option 1</div>
<div class="demo--panel--opt-2" hidden>Show Option 2</div>
<div class="demo--panel--opt-3" hidden>Show Option 3</div>

Preset an active button and panel with JavaScript

Use setActive class method to preset the selection on a Content Switcher; doing this will avoid manually adding bx--content-switcher--selected modifier class and hidden attributes on HTML.

<div
  data-content-switcher
  id="my-content-switcher"
  class="bx--content-switcher"
>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-1">
    Option 1
  </button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2">
    Option 2
  </button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3">
    Option 3
  </button>
</div>
<div class="demo--panel--opt-1">Show Option 1</div>
<div class="demo--panel--opt-2">Show Option 2</div>
<div class="demo--panel--opt-3">Show Option 3</div>
// Get HTMLelement for button to preselect it with setActive
const button = document.querySelector('[data-target=".demo--panel--opt-2"]');
// Initialize an instance of ContentSwitcher with init(), create(element) or new ContentSwitcher(element)
ContentSwitcher.init();
// Grab an ContentSwitcher instance
const instance = ContentSwitcher.components.get(
  document.getElementById('my-content-switcher')
);
// Use setActive
instance.setActive(button);

The setActive method also takes an optional callback function parameter. The most typical example of using this is acting on a newly selected content-switcher button.

contentSwitcher.setActive(button, function(error, item) {
  if (!error) {
    // Having no error means that content switching is not canceled, so go on…
    item.ownerDocument
      .querySelector(item.dataset.target)
      .querySelector('input')
      .focus(); // `item` is the newly selected button
  }
});

Using buttons or anchor elements are both fine

Content Switcher can be implemented with either <button> or <a> elements for its click targets. Both uses of HTML will render the same visual styles and interactions.

<div data-content-switcher class="bx--content-switcher">
  <a
    href="javascript:void(0)"
    class="bx--content-switcher-btn bx--content-switcher--selected"
    data-target=".demo--panel--opt-1"
    >Option 1</a
  >
  <a
    href="javascript:void(0)"
    class="bx--content-switcher-btn"
    data-target=".demo--panel--opt-2"
    >Option 2</a
  >
  <a
    href="javascript:void(0)"
    class="bx--content-switcher-btn"
    data-target=".demo--panel--opt-3"
    >Option 3</a
  >
</div>
<div data-content-switcher class="bx--content-switcher">
  <button
    class="bx--content-switcher-btn bx--content-switcher--selected"
    data-target=".demo--panel--opt-1"
  >
    Option 1
  </button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2">
    Option 2
  </button>
  <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3">
    Option 3
  </button>
</div>