Struct Tabs

pub struct Tabs<'a> { /* private fields */ }

A widget that displays a horizontal set of Tabs with a single tab selected.

Each tab title is stored as a Line which can be individually styled. The selected tab is set using Tabs::select and styled using Tabs::highlight_style. The divider can be customized with Tabs::divider. Padding can be set with Tabs::padding or Tabs::padding_left and Tabs::padding_right.

The divider defaults to |, and padding defaults to a singular space on each side.

Example

use ratatui::{
    style::{Style, Stylize},
    symbols,
    widgets::{Block, Tabs},
};

Tabs::new(vec!["Tab1", "Tab2", "Tab3", "Tab4"])
    .block(Block::bordered().title("Tabs"))
    .style(Style::default().white())
    .highlight_style(Style::default().yellow())
    .select(2)
    .divider(symbols::DOT)
    .padding("->", "<-");

In addition to Tabs::new, any iterator whose element is convertible to Line can be collected into Tabs.

use ratatui::widgets::Tabs;

(0..5).map(|i| format!("Tab{i}")).collect::<Tabs>();

Implementations

impl<'a> Tabs<'a>

pub fn new<Iter>(titles: Iter) -> Self

where Iter: IntoIterator, Iter::Item: Into<Line<'a>>,

Creates new Tabs from their titles.

titles can be a Vec of &str, String or anything that can be converted into Line. As such, titles can be styled independently.

The selected tab can be set with Tabs::select. The first tab has index 0 (this is also the default index).

The selected tab can have a different style with Tabs::highlight_style. This defaults to a style with the Modifier::REVERSED modifier added.

The default divider is a pipe (|), but it can be customized with Tabs::divider.

The entire widget can be styled with Tabs::style.

The widget can be wrapped in a Block using Tabs::block.

Examples

Basic titles.

use ratatui::widgets::Tabs;

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]);

Styled titles

use ratatui::{style::Stylize, widgets::Tabs};

let tabs = Tabs::new(vec!["Tab 1".red(), "Tab 2".blue()]);

Examples found in repository

examples/tabs.rs (line 136)

    fn render_tabs(&self, area: Rect, buf: &mut Buffer) {
        let titles = SelectedTab::iter().map(SelectedTab::title);
        let highlight_style = (Color::default(), self.selected_tab.palette().c700);
        let selected_tab_index = self.selected_tab as usize;
        Tabs::new(titles)
            .highlight_style(highlight_style)
            .select(selected_tab_index)
            .padding("", "")
            .divider(" ")
            .render(area, buf);
    }

examples/flex.rs (line 278)

    fn tabs(self) -> impl Widget {
        let tab_titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
        let block = Block::new()
            .title("Flex Layouts ".bold())
            .title(" Use ◄ ► to change tab, ▲ ▼  to scroll, - + to change spacing ");
        Tabs::new(tab_titles)
            .block(block)
            .highlight_style(Modifier::REVERSED)
            .select(self.selected_tab as usize)
            .divider(" ")
            .padding("", "")
    }

examples/demo2/app.rs (line 163)

    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
        let layout = Layout::horizontal([Constraint::Min(0), Constraint::Length(43)]);
        let [title, tabs] = layout.areas(area);

        Span::styled("Ratatui", THEME.app_title).render(title, buf);
        let titles = Tab::iter().map(Tab::title);
        Tabs::new(titles)
            .style(THEME.tabs)
            .highlight_style(THEME.tabs_selected)
            .select(self.tab as usize)
            .divider("")
            .padding("", "")
            .render(tabs, buf);
    }

examples/demo2/tabs/email.rs (line 86)

fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
    let [tabs, inbox] = vertical.areas(area);
    let theme = THEME.email;
    Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
        .style(theme.tabs)
        .highlight_style(theme.tabs_selected)
        .select(0)
        .divider("")
        .render(tabs, buf);

    let highlight_symbol = ">>";
    let from_width = EMAILS
        .iter()
        .map(|e| e.from.width())
        .max()
        .unwrap_or_default();
    let items = EMAILS.iter().map(|e| {
        let from = format!("{:width$}", e.from, width = from_width).into();
        ListItem::new(Line::from(vec![from, " ".into(), e.subject.into()]))
    });
    let mut state = ListState::default().with_selected(Some(selected_index));
    StatefulWidget::render(
        List::new(items)
            .style(theme.inbox)
            .highlight_style(theme.selected_item)
            .highlight_symbol(highlight_symbol),
        inbox,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(EMAILS.len())
        .position(selected_index);
    Scrollbar::default()
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▐")
        .render(inbox, buf, &mut scrollbar_state);
}

pub fn titles<Iter>(self, titles: Iter) -> Self

where Iter: IntoIterator, Iter::Item: Into<Line<'a>>,

Sets the titles of the tabs.

titles is an iterator whose elements can be converted into Line.

The selected tab can be set with Tabs::select. The first tab has index 0 (this is also the default index).

Examples

Basic titles.

use ratatui::widgets::Tabs;

let tabs = Tabs::default().titles(vec!["Tab 1", "Tab 2"]);

Styled titles.

use ratatui::{style::Stylize, widgets::Tabs};

let tabs = Tabs::default().titles(vec!["Tab 1".red(), "Tab 2".blue()]);

pub fn block(self, block: Block<'a>) -> Self

Surrounds the Tabs with a Block.

Examples found in repository

examples/flex.rs (line 279)

    fn tabs(self) -> impl Widget {
        let tab_titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
        let block = Block::new()
            .title("Flex Layouts ".bold())
            .title(" Use ◄ ► to change tab, ▲ ▼  to scroll, - + to change spacing ");
        Tabs::new(tab_titles)
            .block(block)
            .highlight_style(Modifier::REVERSED)
            .select(self.selected_tab as usize)
            .divider(" ")
            .padding("", "")
    }

pub fn select<T: Into<Option<usize>>>(self, selected: T) -> Self

Sets the selected tab.

The first tab has index 0 (this is also the default index). The selected tab can have a different style with Tabs::highlight_style.

Examples

Select the second tab.

use ratatui::widgets::Tabs;

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).select(1);

Deselect the selected tab.

use ratatui::widgets::Tabs;

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).select(None);

Examples found in repository

examples/tabs.rs (line 138)

    fn render_tabs(&self, area: Rect, buf: &mut Buffer) {
        let titles = SelectedTab::iter().map(SelectedTab::title);
        let highlight_style = (Color::default(), self.selected_tab.palette().c700);
        let selected_tab_index = self.selected_tab as usize;
        Tabs::new(titles)
            .highlight_style(highlight_style)
            .select(selected_tab_index)
            .padding("", "")
            .divider(" ")
            .render(area, buf);
    }

examples/flex.rs (line 281)

    fn tabs(self) -> impl Widget {
        let tab_titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
        let block = Block::new()
            .title("Flex Layouts ".bold())
            .title(" Use ◄ ► to change tab, ▲ ▼  to scroll, - + to change spacing ");
        Tabs::new(tab_titles)
            .block(block)
            .highlight_style(Modifier::REVERSED)
            .select(self.selected_tab as usize)
            .divider(" ")
            .padding("", "")
    }

examples/demo2/app.rs (line 166)

    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
        let layout = Layout::horizontal([Constraint::Min(0), Constraint::Length(43)]);
        let [title, tabs] = layout.areas(area);

        Span::styled("Ratatui", THEME.app_title).render(title, buf);
        let titles = Tab::iter().map(Tab::title);
        Tabs::new(titles)
            .style(THEME.tabs)
            .highlight_style(THEME.tabs_selected)
            .select(self.tab as usize)
            .divider("")
            .padding("", "")
            .render(tabs, buf);
    }

examples/demo2/tabs/email.rs (line 89)

fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
    let [tabs, inbox] = vertical.areas(area);
    let theme = THEME.email;
    Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
        .style(theme.tabs)
        .highlight_style(theme.tabs_selected)
        .select(0)
        .divider("")
        .render(tabs, buf);

    let highlight_symbol = ">>";
    let from_width = EMAILS
        .iter()
        .map(|e| e.from.width())
        .max()
        .unwrap_or_default();
    let items = EMAILS.iter().map(|e| {
        let from = format!("{:width$}", e.from, width = from_width).into();
        ListItem::new(Line::from(vec![from, " ".into(), e.subject.into()]))
    });
    let mut state = ListState::default().with_selected(Some(selected_index));
    StatefulWidget::render(
        List::new(items)
            .style(theme.inbox)
            .highlight_style(theme.selected_item)
            .highlight_symbol(highlight_symbol),
        inbox,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(EMAILS.len())
        .position(selected_index);
    Scrollbar::default()
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▐")
        .render(inbox, buf, &mut scrollbar_state);
}

pub fn style<S: Into<Style>>(self, style: S) -> Self

Sets the style of the tabs.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This will set the given style on the entire render area. More precise style can be applied to the titles by styling the ones given to Tabs::new. The selected tab can be styled differently using Tabs::highlight_style.

Examples found in repository

examples/demo2/app.rs (line 164)

    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
        let layout = Layout::horizontal([Constraint::Min(0), Constraint::Length(43)]);
        let [title, tabs] = layout.areas(area);

        Span::styled("Ratatui", THEME.app_title).render(title, buf);
        let titles = Tab::iter().map(Tab::title);
        Tabs::new(titles)
            .style(THEME.tabs)
            .highlight_style(THEME.tabs_selected)
            .select(self.tab as usize)
            .divider("")
            .padding("", "")
            .render(tabs, buf);
    }

examples/demo2/tabs/email.rs (line 87)

fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
    let [tabs, inbox] = vertical.areas(area);
    let theme = THEME.email;
    Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
        .style(theme.tabs)
        .highlight_style(theme.tabs_selected)
        .select(0)
        .divider("")
        .render(tabs, buf);

    let highlight_symbol = ">>";
    let from_width = EMAILS
        .iter()
        .map(|e| e.from.width())
        .max()
        .unwrap_or_default();
    let items = EMAILS.iter().map(|e| {
        let from = format!("{:width$}", e.from, width = from_width).into();
        ListItem::new(Line::from(vec![from, " ".into(), e.subject.into()]))
    });
    let mut state = ListState::default().with_selected(Some(selected_index));
    StatefulWidget::render(
        List::new(items)
            .style(theme.inbox)
            .highlight_style(theme.selected_item)
            .highlight_symbol(highlight_symbol),
        inbox,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(EMAILS.len())
        .position(selected_index);
    Scrollbar::default()
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▐")
        .render(inbox, buf, &mut scrollbar_state);
}

pub fn highlight_style<S: Into<Style>>(self, style: S) -> Self

Sets the style for the highlighted tab.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

Highlighted tab can be selected with Tabs::select.

Examples found in repository

examples/tabs.rs (line 137)

    fn render_tabs(&self, area: Rect, buf: &mut Buffer) {
        let titles = SelectedTab::iter().map(SelectedTab::title);
        let highlight_style = (Color::default(), self.selected_tab.palette().c700);
        let selected_tab_index = self.selected_tab as usize;
        Tabs::new(titles)
            .highlight_style(highlight_style)
            .select(selected_tab_index)
            .padding("", "")
            .divider(" ")
            .render(area, buf);
    }

examples/flex.rs (line 280)

    fn tabs(self) -> impl Widget {
        let tab_titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
        let block = Block::new()
            .title("Flex Layouts ".bold())
            .title(" Use ◄ ► to change tab, ▲ ▼  to scroll, - + to change spacing ");
        Tabs::new(tab_titles)
            .block(block)
            .highlight_style(Modifier::REVERSED)
            .select(self.selected_tab as usize)
            .divider(" ")
            .padding("", "")
    }

examples/demo2/app.rs (line 165)

    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
        let layout = Layout::horizontal([Constraint::Min(0), Constraint::Length(43)]);
        let [title, tabs] = layout.areas(area);

        Span::styled("Ratatui", THEME.app_title).render(title, buf);
        let titles = Tab::iter().map(Tab::title);
        Tabs::new(titles)
            .style(THEME.tabs)
            .highlight_style(THEME.tabs_selected)
            .select(self.tab as usize)
            .divider("")
            .padding("", "")
            .render(tabs, buf);
    }

examples/demo2/tabs/email.rs (line 88)

fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
    let [tabs, inbox] = vertical.areas(area);
    let theme = THEME.email;
    Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
        .style(theme.tabs)
        .highlight_style(theme.tabs_selected)
        .select(0)
        .divider("")
        .render(tabs, buf);

    let highlight_symbol = ">>";
    let from_width = EMAILS
        .iter()
        .map(|e| e.from.width())
        .max()
        .unwrap_or_default();
    let items = EMAILS.iter().map(|e| {
        let from = format!("{:width$}", e.from, width = from_width).into();
        ListItem::new(Line::from(vec![from, " ".into(), e.subject.into()]))
    });
    let mut state = ListState::default().with_selected(Some(selected_index));
    StatefulWidget::render(
        List::new(items)
            .style(theme.inbox)
            .highlight_style(theme.selected_item)
            .highlight_symbol(highlight_symbol),
        inbox,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(EMAILS.len())
        .position(selected_index);
    Scrollbar::default()
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▐")
        .render(inbox, buf, &mut scrollbar_state);
}

pub fn divider<T>(self, divider: T) -> Self

where T: Into<Span<'a>>,

Sets the string to use as tab divider.

By default, the divider is a pipe (|).

Examples

Use a dot (•) as separator.

use ratatui::{symbols, widgets::Tabs};

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).divider(symbols::DOT);

Use dash (-) as separator.

use ratatui::widgets::Tabs;

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).divider("-");

Examples found in repository

examples/tabs.rs (line 140)

    fn render_tabs(&self, area: Rect, buf: &mut Buffer) {
        let titles = SelectedTab::iter().map(SelectedTab::title);
        let highlight_style = (Color::default(), self.selected_tab.palette().c700);
        let selected_tab_index = self.selected_tab as usize;
        Tabs::new(titles)
            .highlight_style(highlight_style)
            .select(selected_tab_index)
            .padding("", "")
            .divider(" ")
            .render(area, buf);
    }

examples/flex.rs (line 282)

    fn tabs(self) -> impl Widget {
        let tab_titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
        let block = Block::new()
            .title("Flex Layouts ".bold())
            .title(" Use ◄ ► to change tab, ▲ ▼  to scroll, - + to change spacing ");
        Tabs::new(tab_titles)
            .block(block)
            .highlight_style(Modifier::REVERSED)
            .select(self.selected_tab as usize)
            .divider(" ")
            .padding("", "")
    }

examples/demo2/app.rs (line 167)

    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
        let layout = Layout::horizontal([Constraint::Min(0), Constraint::Length(43)]);
        let [title, tabs] = layout.areas(area);

        Span::styled("Ratatui", THEME.app_title).render(title, buf);
        let titles = Tab::iter().map(Tab::title);
        Tabs::new(titles)
            .style(THEME.tabs)
            .highlight_style(THEME.tabs_selected)
            .select(self.tab as usize)
            .divider("")
            .padding("", "")
            .render(tabs, buf);
    }

examples/demo2/tabs/email.rs (line 90)

fn render_inbox(selected_index: usize, area: Rect, buf: &mut Buffer) {
    let vertical = Layout::vertical([Constraint::Length(1), Constraint::Min(0)]);
    let [tabs, inbox] = vertical.areas(area);
    let theme = THEME.email;
    Tabs::new(vec![" Inbox ", " Sent ", " Drafts "])
        .style(theme.tabs)
        .highlight_style(theme.tabs_selected)
        .select(0)
        .divider("")
        .render(tabs, buf);

    let highlight_symbol = ">>";
    let from_width = EMAILS
        .iter()
        .map(|e| e.from.width())
        .max()
        .unwrap_or_default();
    let items = EMAILS.iter().map(|e| {
        let from = format!("{:width$}", e.from, width = from_width).into();
        ListItem::new(Line::from(vec![from, " ".into(), e.subject.into()]))
    });
    let mut state = ListState::default().with_selected(Some(selected_index));
    StatefulWidget::render(
        List::new(items)
            .style(theme.inbox)
            .highlight_style(theme.selected_item)
            .highlight_symbol(highlight_symbol),
        inbox,
        buf,
        &mut state,
    );
    let mut scrollbar_state = ScrollbarState::default()
        .content_length(EMAILS.len())
        .position(selected_index);
    Scrollbar::default()
        .begin_symbol(None)
        .end_symbol(None)
        .track_symbol(None)
        .thumb_symbol("▐")
        .render(inbox, buf, &mut scrollbar_state);
}

pub fn padding<T, U>(self, left: T, right: U) -> Self

where T: Into<Line<'a>>, U: Into<Line<'a>>,

Sets the padding between tabs.

Both default to space.

Examples

A space on either side of the tabs.

use ratatui::widgets::Tabs;

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).padding(" ", " ");

Nothing on either side of the tabs.

use ratatui::widgets::Tabs;

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).padding("", "");

Examples found in repository

examples/tabs.rs (line 139)

    fn render_tabs(&self, area: Rect, buf: &mut Buffer) {
        let titles = SelectedTab::iter().map(SelectedTab::title);
        let highlight_style = (Color::default(), self.selected_tab.palette().c700);
        let selected_tab_index = self.selected_tab as usize;
        Tabs::new(titles)
            .highlight_style(highlight_style)
            .select(selected_tab_index)
            .padding("", "")
            .divider(" ")
            .render(area, buf);
    }

examples/flex.rs (line 283)

    fn tabs(self) -> impl Widget {
        let tab_titles = SelectedTab::iter().map(SelectedTab::to_tab_title);
        let block = Block::new()
            .title("Flex Layouts ".bold())
            .title(" Use ◄ ► to change tab, ▲ ▼  to scroll, - + to change spacing ");
        Tabs::new(tab_titles)
            .block(block)
            .highlight_style(Modifier::REVERSED)
            .select(self.selected_tab as usize)
            .divider(" ")
            .padding("", "")
    }

examples/demo2/app.rs (line 168)

    fn render_title_bar(&self, area: Rect, buf: &mut Buffer) {
        let layout = Layout::horizontal([Constraint::Min(0), Constraint::Length(43)]);
        let [title, tabs] = layout.areas(area);

        Span::styled("Ratatui", THEME.app_title).render(title, buf);
        let titles = Tab::iter().map(Tab::title);
        Tabs::new(titles)
            .style(THEME.tabs)
            .highlight_style(THEME.tabs_selected)
            .select(self.tab as usize)
            .divider("")
            .padding("", "")
            .render(tabs, buf);
    }

pub fn padding_left<T>(self, padding: T) -> Self

where T: Into<Line<'a>>,

Sets the left side padding between tabs.

Defaults to a space.

Example

An arrow on the left of tabs.

use ratatui::widgets::Tabs;

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).padding_left("->");

pub fn padding_right<T>(self, padding: T) -> Self

where T: Into<Line<'a>>,

Sets the right side padding between tabs.

Defaults to a space.

Example

An arrow on the right of tabs.

use ratatui::widgets::Tabs;

let tabs = Tabs::new(vec!["Tab 1", "Tab 2"]).padding_right("<-");

Trait Implementations

impl<'a> Clone for Tabs<'a>

fn clone(&self) -> Tabs<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Tabs<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Tabs<'_>

fn default() -> Self

Returns a default Tabs widget.

The default widget has:

• No tabs
• No selected tab
• The highlight style is set to reversed.
• The divider is set to a pipe (|).
• The padding on the left and right is set to a space.

This is rarely useful on its own without calling Tabs::titles.

Examples

use ratatui::widgets::Tabs;

let tabs = Tabs::default().titles(["Tab 1", "Tab 2"]);

impl<'a, Item> FromIterator<Item> for Tabs<'a>

where Item: Into<Line<'a>>,

fn from_iter<Iter: IntoIterator<Item = Item>>(iter: Iter) -> Self

Creates a value from an iterator.

impl<'a> Hash for Tabs<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq for Tabs<'a>

fn eq(&self, other: &Tabs<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Styled for Tabs<'a>

type Item = Tabs<'a>

fn style(&self) -> Style

Returns the style of the object.

fn set_style<S: Into<Style>>(self, style: S) -> Self::Item

Sets the style of the object.

impl Widget for Tabs<'_>

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl WidgetRef for Tabs<'_>

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Available on crate feature unstable-widget-ref only.

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl<'a> Eq for Tabs<'a>

impl<'a> StructuralPartialEq for Tabs<'a>