react-dyn-tabs
Create responsive and dynamic tabs in React. This library supports ARIA accessibility and provides complete control over tab management using hooks.
Screenshot
Demo
Features
- Responsive (using
more button
) - Full API (Open & Close & Select & Refresh & setOption & setTab, ...)
- lazy loading and rendering
- Customizable style
- Return to last used tab when closing selected tab
- PanelList can be rendered outside the TabList container
- RTL & Vertical Mode
- ARIA accessible
- Customizable Tab component
- Multiple themes
- The core is about 23kb
Table of Contents
Installation
$ npm install react-dyn-tabs --save
or
$ yarn add react-dyn-tabs
If you need to directly include script in your html, use the following link :
<script src="https://unpkg.com/react-dyn-tabs@latest/dist/react-dyn-tabs.umd.min.js"></script>
Syntax
[TabList, PanelList, ready] = useDynTabs(initialOptions, plugins);
Minimal Usage Example
import React from 'react';
import 'react-dyn-tabs/style/react-dyn-tabs.css';
import 'react-dyn-tabs/themes/react-dyn-tabs-card.css';
import useDynTabs from 'react-dyn-tabs';
const initialOptions = {
tabs: [
{
id: '1',
title: 'tab 1',
panelComponent: (props) => <p> panel 1 </p>,
},
{
id: '2',
title: 'tab 2',
panelComponent: (props) => <p> panel 2 </p>,
},
],
selectedTabID: '1',
};
export default () => {
const [TabList, PanelList] = useDynTabs(initialOptions);
return (
<div>
<TabList></TabList>
<PanelList></PanelList>
</div>
);
};
Simple Manipulation Example
import React from 'react';
import 'react-dyn-tabs/style/scss/react-dyn-tabs.scss';
import 'react-dyn-tabs/themes/scss/react-dyn-tabs-card.scss';
import useDynTabs from 'react-dyn-tabs';
const initialOptions = {
tabs: [
{
id: '1',
title: 'tab1',
panelComponent: (props) => <p> panel 1 </p>,
},
{
id: '2',
title: 'tab2',
panelComponent: (props) => <p> panel 2 </p>,
},
],
selectedTabID: '1',
};
export default () => {
const [TabList, PanelList, ready] = useDynTabs(initialOptions);
const addTab3 = function () {
ready((instance) => {
instance.open({id: '3', title: 'Tab 3', panelComponent: (props) => <p> panel 3 </p>}).then(() => {
console.log('tab 3 is open');
});
instance.select('3').then(() => {
console.log('tab 3 is selected');
});
});
};
return (
<div>
<button onClick={addTab3}>Add tab 3</button>
<TabList></TabList>
<PanelList></PanelList>
</div>
);
};
NOTE :
-
Use ready
function to access the instance
object
ready((instance) => {
});
-
ready
function accepts a callback
as its parameter and executes it as soon as Tabs get mounted.
-
If ready
function is called after the Tabs has been mounted, the callback
passed in will be executed immediately.
-
ready
function can be executed multiple times and its identity is stable and won’t change on re-renders.
Options
tabs
type | default value | required | description |
---|
Array of tabData
| [] | false | initial opened tabs |
Example
const [TabList, PanelList, ready] = useDynTabs({
tabs: [
{
id: '1',
title: 'home',
iconClass: 'fa fa-home',
closable: true,
panelComponent: (props) => <p> home content </p>,
},
{
id: '2',
title: 'contact',
tooltip: 'contact',
disable: true,
closable: false,
panelComponent: (props) => <p> contact content </p>,
},
],
});
selectedTabID
type | default value | required | description |
---|
string | ' ' | false | specifies initial selected tab |
Example
const [TabList, PanelList, ready] = useDynTabs({
tabs: [
{
id: '1',
title: 'home',
iconClass: 'fa fa-home',
closable: true,
panelComponent: (props) => <p> home content </p>,
},
{
id: '2',
title: 'contact',
tooltip: 'contact',
disable: true,
closable: false,
panelComponent: (props) => <p> contact content </p>,
},
],
selectedTabID: '2',
});
direction
type | default value | required | description |
---|
string | 'ltr' | false | can be either of 'ltr' or 'rtl' |
Example
const [TabList, PanelList, ready] = useDynTabs({direction: 'rtl'});
tabComponent
type | required | description |
---|
React component | false | custom tab component |
Example
const [TabList, PanelList, ready] = useDynTabs({
tabComponent: (props) => {
const {id, isSelected, api: instance} = props;
return (
<button {...props.tabProps}>
{props.children}
{props.iconProps && <span {...props.iconProps}></span>}
</button>
);
},
});
defaultPanelComponent
Default value for panelComponent
option.
type | required | description |
---|
React component | React element | false | |
Example
const [TabList, PanelList, ready] = useDynTabs({
defaultPanelComponent: (props) => {
const {id, isSelected, api: instance} = props;
return <div>loading...</div>;
},
});
accessibility
type | default value | required | description |
---|
boolean | true | false | |
Example
const [TabList, PanelList, ready] = useDynTabs({accessibility: false});
NOTE :
When accessibility
option is true
, it sets the id attribute of panel
and button
elements.
isVertical
type | default value | required | description |
---|
boolean | false | false | |
Example
const [TabList, PanelList, ready] = useDynTabs({isVertical: true});
theme
type | required | description |
---|
string | no | the chosen theme name when you have multiple themes CSS. |
Examples
-
in this exmaple, only bootstrap
theme is applied to the Tablist
, because value of theme
option is bootstrap
import 'react-dyn-tabs/themes/react-dyn-tabs-card.css';
import 'react-dyn-tabs/themes/react-dyn-tabs-bootstrap.css';
import 'react-dyn-tabs/themes/react-dyn-tabs-classic.css';
import 'react-dyn-tabs/themes/react-dyn-tabs-basic.css';
...
useDynTabs({theme:'bootstrap'});
-
in this exmaple, only classic
theme is applied to the Tablist
, because value of theme
option is classic
import 'react-dyn-tabs/themes/react-dyn-tabs-card.css';
import 'react-dyn-tabs/themes/react-dyn-tabs-bootstrap.css';
import 'react-dyn-tabs/themes/react-dyn-tabs-classic.css';
import 'react-dyn-tabs/themes/react-dyn-tabs-basic.css';
...
useDynTabs({theme:'classic'});
tablistStyle
type | default value | required | description |
---|
object | {} | no | sets the style object for root element of Tablist |
Example
const [TabList, PanelList, ready] = useDynTabs({
tablistStyle: {backgroundColor: 'blue'},
});
onLoad
type | required | description |
---|
function | false | This event is fired only once, when Tabs are mounted |
Example
const [TabList, PanelList, ready] = useDynTabs({
onLoad: function () {
console.log('[onLoad]');
},
});
NOTE :
You can use this
keyword inside all callback options. It refers to the instance
object.
onInit
type | required | description |
---|
function | false | This event is triggered after every render. |
Example
const [TabList, PanelList, ready] = useDynTabs({
onInit: function () {
console.log('[onInit]');
},
});
NOTE :
Do not use setState
inside the onInit
callback because it leads to an infinite loop.
onChange
type | required | description |
---|
function | false | fires when we open|close|select a tab. this event is not fired initially |
Example
const [TabList, PanelList, ready] = useDynTabs({
onChange: function ({currentData, previousData, closedTabIDs, openedTabIDs}) {
console.log('[onChange]');
},
});
beforeSelect
type | required | description |
---|
function | false |
Fires when the user clicks on the tab, but before select them.
This event should return boolean true or false, If the event returns false the tab is not selected.
|
Example
const [TabList, PanelList, ready] = useDynTabs({
beforeSelect: function (e, id) {
console.log('[beforeSelect]');
return true;
},
});
onFirstSelect
type | required | description |
---|
function | false | fires after selecting a tab for the first time. It is not fired for the initial selected tab |
Example
const [TabList, PanelList, ready] = useDynTabs({
onFirstSelect: function ({currentSelectedTabId, previousSelectedTabId}) {
console.log('[onFirstSelect]');
},
});
onSelect
type | required | description |
---|
function | false | fires after selecting a tab. this event is not fired for the initial selected tab |
Example
const [TabList, PanelList, ready] = useDynTabs({
onSelect: function ({currentSelectedTabId, previousSelectedTabId}) {
console.log('[onSelect]');
},
});
onOpen
type | required | description |
---|
function | false | fires after opening tabs. this event is not fired for initial opened tabs |
Example
const [TabList, PanelList, ready] = useDynTabs({
onOpen: function (openedTabIDs) {
console.log('[onOpen]');
},
});
beforeClose
type | required | description |
---|
function | false |
fires when the user clicks on the close icon, but before close them.
This event should return boolean true or false, If the event return false the tab is not closed.
|
Example
const [TabList, PanelList, ready] = useDynTabs({
beforeClose: function (e, id) {
console.log('[beforeClose]');
return true;
},
});
onClose
type | required | description |
---|
function | false | fires after closing tabs |
Example
const [TabList, PanelList, ready] = useDynTabs({
onClose: function (closedTabIDs) {
console.log('[onClose]');
},
});
onDestroy
type | required | description |
---|
function | false | fires before destroying useDynTabs hook |
Example
const [TabList, PanelList, ready] = useDynTabs({
onDestroy: function () {
console.log('[onDestroy]');
},
});
Instance methods
isOpen
Return value : boolean
Parameters:
Example
const result = instance.isOpen('Your tab ID');
open
Triggers onInit
, onChange
and onOpen
events.
It only triggers onInit
event, if the tab is already open.
Return value : Promise
Parameters:
Example
if (instance.isOpen('contact') == false) {
instance
.open({
id: 'contact',
title: 'contact',
tooltip: 'contact',
disable: false,
closable: true,
iconClass: '',
panelComponent: <ContactPanel></ContactPanel>,
})
.then(({currentData, instance}) => {
console.log('contact tab is open');
});
}
isSelected
Return value : boolean
Parameters:
Example
const result = instance.isSelected('Your tab ID');
select
Makes current and previous selected tab to be re-rendered
Triggers onInit
, onChange
and onSelect
events.
It only triggers onInit
event, if the tab is already selected.
Return value : Promise
Parameters:
Example
if (instance.isSelected('1') == false) {
instance.select('1').then(({currentData, instance}) => {
console.log('tab 1 is selected');
});
}
close
Triggers onInit
, onChange
and onClose
events.
It only triggers onInit
event, if the tab is already closed.
When switching
parameter is true
, it switches to previous selected tab
Return value : Promise
Parameters:
id: string
switching: boolean (default : true)
Example
if (instance.isOpen('2') == true) {
instance.close('2').then(({currentData, instance}) => {
console.log('tab 2 is closed');
});
}
refresh
Makes all tabs to be re-rendered.
triggers onInit
event.
Return value : Promise
Example
instance.refresh().then(({currentData, instance}) => {});
getOption
Parameters:
Example
const direction = instance.getOption('direction');
const onSelect = instance.getOption('onSelect');
setOption
Can be used for setting all options except selectedTabID
and tabs
options.
This function does not re-render Tabs. If you need to re-render Tabs, use refresh
method after this function.
Return value : instance object
Parameters:
optionName : String
optionValue : string|boolean|object|function
Example
instance.setOption('direction', 'rtl');
instance.setOption('onSelect', () => {});
instance.setOption('beforeSelect', () => false);
getTab
Get tabData
object
Return value : tabData object
Parameters:
Example
const {id, title, tooltip, disable, lazy, iconClass, closable, panelComponent} = instance.getTab('contactID');
console.log(id);
setTab
Set tabData
object.
This function does not re-render Tabs. If you need to re-render Tabs, use refresh
method after this function.
Return value : instance object
Parameters:
tab id : String
source object : containing the properties you want to apply
Example
instance.setTab('home', {disable: true});
instance.setTab('contact', {closable: false, panelComponent: (props) => <p>contact panel</p>});
on
Attach an event handler function for one event.
Return value : instance object
Parameters:
event Name : String (can be either of onFirstSelect|onSelect|onClose|onOpen|onInit|onChange|onDestroy)
handler : function
Example
const handler = React.useCallback(function (params) {
const {currentSelectedTabId, previousSelectedTabId} = params;
}, []);
instance.on('onSelect', handler);
one
Attach a handler to an event. The handler is executed at most once.
Return value : instance object
Parameters:
event Name : String (can be either of onFirstSelect|onSelect|onClose|onOpen|onInit|onChange|onDestroy)
handler : function
Example
instance.one('onSelect', function ({currentSelectedTabId, previousSelectedTabId}) {});
off
Remove an event handler.
Return value : instance object
Parameters:
event Name : String (can be either of onFirstSelect|onSelect|onClose|onOpen|onInit|onChange|onDestroy)
handler : function (A handler function previously attached for the event)
Example
const handler = React.useCallback(function () {}, []);
const attachHandler = () => {
instance.on('onSelect', handler);
};
const deattachHandler = () => {
instance.off('onSelect', handler);
};
getData
Get a copy of data
Return value : Data
Object
Example
const {selectedTabID, openTabIDs} = instance.getData();
NOTE :
getCopyData
function is an older version of getData
function and it is enabled by default so that existing users do not have to change their code. You are free to use both conventions.
getPreviousData
Get a copy of data in previous render
Return value : Data
Object
Example
const {selectedTabID, openTabIDs} = instance.getPreviousData();
NOTE :
getCopyPerviousData
function is an older version of getPreviousData
function and it is enabled by default so that existing users do not have to change their code. You are free to use both conventions.
sort
Useful for sorting Tabs manually.
Triggers onInit
event.
Return value : Promise
Parameters:
Example
const {openTabIDs} = instance.getData();
instance.sort(openTabIDs.reverse()).then(({currentData, instance}) => {
console.log('sorting Tabs has finished');
});
tabData
property name | type | default value | required | description |
---|
id | string | | false | an unique identifier for each tab |
title | string | ' ' | false | |
tooltip | string | ' ' | false | |
panelComponent | React Element | React Component | null | A function component which returns empty div | false | |
lazy | boolean | false | false |
If set to false the panel will be rendered initially.
if set to true the panel will not be rendered until the tab is activated
|
closable | boolean | true | false | |
iconClass | string | ' ' | false | class name for the icon |
disable | boolean | false | false | |
Example
const tabData = {
id: 'contactID',
title: 'contactTitle',
tooltip: 'contactTooltip',
disable: true,
lazy: true,
iconClass: 'fa fa-home',
closable: false,
panelComponent: (props) => <p> contact content </p>,
};
const [TabList, PanelList, ready] = useDynTabs({tabs: [tabData]});
if (instance.isOpen(tabData.id) == false) {
instance.open(tabData).then(() => {});
}
Lazy Loading
Defer loading of tab content until the tab is activated
Example 1
const Panel3 = React.lazy(() => import('./components/panel3.js'));
function LazyLoadingPanel3(props) {
return (
<Suspense fallback={<div>Loading...</div>}>
<Panel3 {...props}></Panel3>
</Suspense>
);
}
useDynTabs({
tabs: [
{id: '1', title: 'eager loading tab 1', panelComponent: <p>panel 1</p>},
{id: '2', title: 'eager loading tab 2', lazy: true, panelComponent: <p>panel 2</p>},
{id: '3', title: 'lazy loading tab 3', lazy: true, panelComponent: LazyLoadingPanel3},
],
selectedTabID: '1',
});
NOTE :
- panel 1 is eagerly loaded and rendered.
- panel 2 is eagerly loaded but will not be rendered until tab 2 is activated.
- panel 3 will not be loaded and rendered until tab 3 is activated.
Example 2 ( using onFirstSelect event )
useDynTabs({
tabs: [
{id: '1', title: 'eager loading tab 1', panelComponent: <p>panel 1</p>},
{id: '2', title: 'eager loading tab 2', lazy: true, panelComponent: <p>panel 2</p>},
{id: '3', title: 'lazy loading tab 3', lazy: true},
],
selectedTabID: '1',
defaultPanelComponent: function DefaultPanel() {
return <div>loading...</div>;
},
onFirstSelect: function ({currentSelectedTabId}) {
const instance = this;
if (currentSelectedTabId === '3') {
import('path to/panel3.js').then((defaultExportedModule) => {
const Panel3 = defaultExportedModule.default;
instance.setTab('3', {panelComponent: Panel3});
instance.refresh();
});
}
},
});
Plugins
More Button Plugin
Make Tabs responsive
Usage
import React from 'react';
import 'react-dyn-tabs/style/react-dyn-tabs.css';
import 'react-dyn-tabs/themes/react-dyn-tabs-card.css';
import useDynTabs from 'react-dyn-tabs';
import MoreButtonPlugin from 'react-dyn-tabs/plugins/moreButtonPlugin';
export default () => {
const [TabList, PanelList, ready] = useDynTabs(initialOptions, [MoreButtonPlugin]);
return (
<div>
<TabList></TabList>
<PanelList></PanelList>
</div>
);
};
Options
option name | type | description |
---|
moreButtonPlugin_buttonComponent | React Function Component | customize root component of more button |
moreButtonPlugin_iconComponent | React Function Component | customize icon component of more button |
moreButtonPlugin_buttonTooltip | string | |
Example
useDynamicTabs(
{
tabs: [
{id: '1', title: 'tab1', panelComponent: <span>tab content 1</span>},
{id: '2', title: 'tab2', panelComponent: <span>tab content 2</span>},
{id: '3', title: 'tab3', panelComponent: <span>tab content 3</span>},
],
selectedTabID: '1',
moreButtonPlugin_iconComponent: ({instance}) => {
return <i className={`fa fa-chevron-${instance.getOption('direction') === 'rtl' ? 'left' : 'right'}`} />;
},
moreButtonPlugin_buttonTooltip: 'show more tabs',
},
[MoreButtonPlugin],
);
Render custom components at the end of the Tablist
-
render new tab
button example :
const [TabList, PanelList, ready] = useDynTabs(initialOptions, [MoreButtonPlugin]);
return (
<div>
<TabList>
<button onClick={()=>{ ready(instance => instance.open({title:'new tab'})) }}>
NEW
</button>
</TabList>
<PanelList></PanelList>
</div>
);
};
-
render close all
button example :
const [TabList, PanelList, ready] = useDynTabs(initialOptions, [MoreButtonPlugin]);
return (
<div>
<TabList>
<button onClick={()=>{ ready(instance=>{ instance.getData().openTabIDs.forEach(id=>instance.close(id,false)); })}}>
CLOSE ALL
</button>
</TabList>
<PanelList></PanelList>
</div>
);
};
Themes And Style
react-dyn-tabs
does not include any style loading by default. Default stylesheets and themes are provided and can be included in your application if desired.
Import the Style
import 'react-dyn-tabs/style/react-dyn-tabs.css';
For rtl
mode you should also import following file
import 'react-dyn-tabs/style/react-dyn-tabs-rtl.css';
Themes
Themes define how the Tabs looks. The library comes with Provided Themes such as card
and bootstrap
. To use a theme you need to 1) import the themes CSS and 2) apply the chosen theme name to the theme
option of the react-dyn-tabs
.
-
card theme
import 'react-dyn-tabs/themes/react-dyn-tabs-card.css';
...
useDynTabs({theme:'card'});
-
bootstrap theme
import 'react-dyn-tabs/themes/react-dyn-tabs-bootstrap.css';
...
useDynTabs({theme:'bootstrap'});
-
basic theme
import 'react-dyn-tabs/themes/react-dyn-tabs-basic.css';
...
useDynTabs({theme:'basic'});
-
classic theme
import 'react-dyn-tabs/themes/react-dyn-tabs-classic.css';
...
useDynTabs({theme:'classic'});
Caveats
-
Some actions like open, select, close and refresh cause re-rendering, and using them immediately after calling useDynTabs hook will create an infinite loop and other bugs that most likely you don't want to cause. you should use them inside event listeners or subscriptions.
-
Do not use setState inside the onInit callback because it leads to an infinite loop.
Test
$ npm run test
License
MIT