grommet
components

Tabs

a container with controls to show one tab at a time

Storybook
CodeSandbox
Github

Props

a11yTitle

Custom label to be used by screen readers. When provided, an aria-label will be added to the element.

string
"a user friendly label for screen readers"

activeIndex

Active tab index. If specified, Tabs will be a controlled component. This means that future tab changes will not work unless you subscribe to onActive function and update activeIndex accordingly.

number
0

alignControls

How to align the tab controls along the vertical axis.

string
"start"
"center"
"end"
"stretch"

alignSelf

How to align along the cross axis when contained in a Box or along the column axis when contained in a Grid.

string
"start"
"center"
"end"
"stretch"

children

Array of Tab.

node
<Tab>...</Tab>

flex

Whether flex-grow and/or flex-shrink is true.

boolean
true
false
string
"grow"
"shrink"

gridArea

The name of the area to place this inside a parent Grid.

string
"a parent grid area name"

justify

How to align the tabs along the main axis.

string
"start"
"center"
"end"

margin

The amount of margin around the component.

string
"none"
"xxsmall"
"xsmall"
"small"
"medium"
"large"
"xlarge"
object

Can be specified to distinguish horizontal margin, vertical margin, and margin on a particular side.


{
    vertical: "...",
    horizontal: "...",
    top: "...",
    bottom: "...",
    left: "...",
    right: "..."
}

messages

Custom messages for Tabs. Used for accessibility by screen readers.

object
{ tabContents: "Tab Contents" }

onActive

Function that will be called with the active tab index when the currently active tab changes.

function
(1) => {}

React/DOM Properties

At its core, the Tabs component is a regular <div> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for div elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

global.borderSize

The size of the border.

string
{
  xsmall: "1px",
  small: "2px",
  medium: "4px",
  large: "12px",
  xlarge: "24px",
}

global.colors.border

The color of tabs border.

string

A hex, name, or rgb value.

"rgba(0, 0, 0, 0.33)"
object

An object with a color for dark and light modes.

{ dark: "rgba(255, 255, 255, 0.33)", light: "rgba(0, 0, 0, 0.33)" }

global.edgeSize.small

The possible sizes for margin, pad and gap.

string
"6px"

tabs.background

Background styling of Tabs.

string

A color or image url.

"neutral-1"
"url(//my.com/assets/img.png)"
object

{
  color: "neutral-1",
  dark: true,
  image: "url(//my.com/assets/img.png)"
  position: "bottom",
  opacity: true,
  repeat: "no-repeat",
  size: "cover",
  light: "string"
}
where opacity could be:
"weak"
"medium"
"strong"
boolean
number
where position could be:
any CSS for background-position
where repeat could be:
"no-repeat"
"repeat"
"string"
where size could be:
"cover"
"contain"
"string"

tabs.extend

Any additional style for Tabs.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

tabs.gap

The gap size between the Tabs.

string
"small"

tabs.header.background

The background styles of Tabs header.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

tabs.header.border.color

Border color of the tabs controls.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

tabs.header.border.side

Side of the border of the tabs controls.

string
"top"

tabs.header.border.size

Border size of the tabs controls.

string
"small"

tabs.header.border.style

Border style of the tabs controls.

string
"solid"

tabs.header.extend

Any additional style for Tabs header.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

tabs.panel.extend

Any additional style for Tabs panel.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

Tab

one tab within tabs

Props

disabled

Whether the tab is disabled.

boolean
true
false

icon

Icon element to place in the tab.

element
<Icon />

plain

Whether this is a plain tab with no style.

boolean
true
false

reverse

Whether an icon and label should be reversed so that the icon is at the end of the tab.

boolean
true
false

title

The title of the tab.

node
"Tab Title"
<Box>...</Box>

React/DOM Properties

At its core, the Tab component is a regular <button> element. Thus, both DOM and React properties, methods, and events are accessible. To read up on all of the possible DOM attributes and types available for button elements, check out this MDN Web Documents page. To learn more about DOM events and methods, you can read more on the MDN Web Events documentation page.

Also, feel free to read about the types of React events available, or see how DOM attributes change in React. Working in tandem with Styled Components, you also have access to the as property.

Theme

tab.active

Styles for the active tab.

object
{color: "text", background: undefined }

tab.background

Background styling of Tab.

string

A color or image url.

"neutral-1"
"url(//my.com/assets/img.png)"
object

{
  color: "neutral-1",
  dark: true,
  image: "url(//my.com/assets/img.png)"
  position: "bottom",
  opacity: true,
  repeat: "no-repeat",
  size: "cover",
  light: "string"
}
where opacity could be:
"weak"
"medium"
"strong"
boolean
number
where position could be:
any CSS for background-position
where repeat could be:
"no-repeat"
"repeat"
"string"
where size could be:
"cover"
"contain"
"string"

tab.border

Border styles of the tab

object

{
  side: "bottom",
  size: "small",
  color: {
    dark: "accent-1",
    light: "brand",
  },
  active: {
    color: {
      dark: "white",
      light: "black",
    },
  },
  hover: {
    color: {
      dark: "white",
      light: "black",
    },
    // extend: undefined,
  },
}

tab.border.disabled.color

Border color of the Tab when disabled

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

tab.color

Text color for the Tab.

string

A hex, name, or rgb value.

"control"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

tab.disabled.color

Text color of the Tab when disabled.

string

A hex, name, or rgb value.

"brand"
object

An object with a color for dark and light modes.

{ dark: "string", light: "string" }

tab.extend

Any additional style for Tab.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

tab.hover.background

Background style of the Tab on hover.

string

A color or image url.

"neutral-1"
"url(//my.com/assets/img.png)"
object

{
  color: "neutral-1",
  dark: true,
  image: "url(//my.com/assets/img.png)"
  position: "bottom",
  opacity: true,
  repeat: "no-repeat",
  size: "cover",
  light: "string"
}
where opacity could be:
"weak"
"medium"
"strong"
boolean
number
where position could be:
any CSS for background-position
where repeat could be:
"no-repeat"
"repeat"
"string"
where size could be:
"cover"
"contain"
"string"

tab.hover.color

Text color of the tab on hover.

string

A hex, name, or rgb value.

"black"
object

An object with a color for dark and light modes.

{ dark: "white", light: "black" }

tab.hover.extend

Any additional style for Tab hover.

string

Any CSS.

css`color: 'blue'`
function
(props) => {}

tab.margin

The margin of Tab.

string
"small"
object
{ vertical: "xxsmall", horizontal: "small" }

tab.pad

The pad of Tab.

string
"small"
object
{ bottom: "xsmall" }