Experimental Content Switcher
<!--
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>First section</span>
</button>
<button class="bx--content-switcher-btn"
data-target=".demo--panel--opt-2" role="tab" >
<span>Second section</span>
</button>
<button class="bx--content-switcher-btn"
data-target=".demo--panel--opt-3" role="tab" >
<span>Third section</span>
</button>
</div>
Experimental Content Switcher with Icon
<!--
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" >
<svg class="bx--content-switcher__icon"
width="16" height="16" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
<path d="M7 7H4v2h3v3h2V9h3V7H9V4H7v3zm1 9A8 8 0 1 1 8 0a8 8 0 0 1 0 16z" fill-rule="evenodd" />
</svg>
<span>First section</span>
</button>
<button class="bx--content-switcher-btn"
data-target=".demo--panel--opt-2" role="tab" >
<svg class="bx--content-switcher__icon"
width="16" height="16" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
<path d="M7 7H4v2h3v3h2V9h3V7H9V4H7v3zm1 9A8 8 0 1 1 8 0a8 8 0 0 1 0 16z" fill-rule="evenodd" />
</svg>
<span>Second section</span>
</button>
<button class="bx--content-switcher-btn"
data-target=".demo--panel--opt-3" role="tab" >
<svg class="bx--content-switcher__icon"
width="16" height="16" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
<path d="M7 7H4v2h3v3h2V9h3V7H9V4H7v3zm1 9A8 8 0 1 1 8 0a8 8 0 0 1 0 16z" fill-rule="evenodd" />
</svg>
<span>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>