In bslib: Custom 'Bootstrap' 'Sass' Themes for 'shiny' and 'rmarkdown'

library(bslib)

knitr::opts_chunk$set(
  ## Screenshots are created during `devtools::document()` in CI
  ## or set to `TRUE` below to test or update locally
  # .update_screenshot = TRUE,
  "fig.width" = 8,
  "fig.height" = 3,
  "dpi" = 100
)

A basic example

This first example creates a simple tabbed navigation container with two tabs. The tab name and the content of each tab are specified in the nav_panel() calls and navset_tab() creates the tabbed navigation around these two tabs.

library(htmltools)

navset_tab(
  nav_panel(title = "One", p("First tab content.")),
  nav_panel(title = "Two", p("Second tab content."))
)

In the rest of the examples, we'll include links among the tabs (or pills) in the navigation controls.

link_shiny <- tags$a(shiny::icon("github"), "Shiny", href = "https://github.com/rstudio/shiny", target = "_blank")
link_posit <- tags$a(shiny::icon("r-project"), "Posit", href = "https://posit.co", target = "_blank")

navset_tab()

You can fully customize the controls in the navigation component. In this example, we've added a direct link to the Shiny repository using nav_item(). We've also included a dropdown menu using nav_menu() containing an option to select a third tab panel and another direct link to Posit's website. Finally, we've separated the primary tabs on the left from the direct link and dropdown menu on the right using nav_spacer().

navset_tab(
  nav_panel(title = "One", p("First tab content.")),
  nav_panel(title = "Two", p("Second tab content.")),
  nav_panel(title = "Three", p("Third tab content")),
  nav_spacer(),
  nav_menu(
    title = "Links",
    nav_item(link_shiny),
    nav_item(link_posit)
  )
)

navset_pill()

navset_pill() creates a navigation container that behaves exactly like navset_tab(), but the tab toggles are pills or button-shaped.

navset_pill(
  nav_panel(title = "One", p("First tab content.")),
  nav_panel(title = "Two", p("Second tab content.")),
  nav_panel(title = "Three", p("Third tab content")),
  nav_spacer(),
  nav_menu(
    title = "Links",
    nav_item(link_shiny),
    nav_item(link_posit)
  )
)

navset_underline()

navset_underline() creates a navigation container that behaves exactly like navset_tab() and navset_pill(), but the active/focused navigation links are styled with an underline.

navset_underline(
  nav_panel(title = "One", p("First tab content.")),
  nav_panel(title = "Two", p("Second tab content.")),
  nav_panel(title = "Three", p("Third tab content")),
  nav_spacer(),
  nav_menu(
    title = "Links",
    nav_item(link_shiny),
    nav_item(link_posit)
  )
)

navset_card_tab()

The tabbed navigation container can also be used in a card() component thanks to navset_card_tab(). Learn more about this approach in the article about Cards, including how to add a shared sidebar to all tabs in the card using the sidebar argument of navset_card_tab().

navset_card_tab(
  nav_panel(title = "One", p("First tab content.")),
  nav_panel(title = "Two", p("Second tab content.")),
  nav_panel(title = "Three", p("Third tab content")),
  nav_spacer(),
  nav_menu(
    title = "Links",
    nav_item(link_shiny),
    nav_item(link_posit)
  )
)

navset_card_pill()

Similar to navset_pill(), navset_card_pill() provides a pill-shaped variant to navset_card_tab(). You can use the placement argument to position the navbar "above" or "below" the card body.

navset_card_pill(
  placement = "above",
  nav_panel(title = "One", p("First tab content.")),
  nav_panel(title = "Two", p("Second tab content.")),
  nav_panel(title = "Three", p("Third tab content")),
  nav_spacer(),
  nav_menu(
    title = "Links",
    nav_item(link_shiny),
    nav_item(link_posit)
  )
)

navset_card_underline()

navset_card_underline() provides a card-based variant of navset_underline().

navset_card_underline(
  nav_panel(title = "One", p("First tab content.")),
  nav_panel(title = "Two", p("Second tab content.")),
  nav_panel(title = "Three", p("Third tab content")),
  nav_spacer(),
  nav_menu(
    title = "Links",
    nav_item(link_shiny),
    nav_item(link_posit)
  )
)

navset_pill_list()

Furthermore, navset_pill_list() creates a vertical list of navigation controls adjacent to, rather than on top of, the tab content panels.

navset_pill_list(
  nav_panel(title = "One", p("First tab content.")),
  nav_panel(title = "Two", p("Second tab content.")),
  nav_panel(title = "Three", p("Third tab content")),
  nav_spacer(),
  nav_menu(
    title = "Links",
    nav_item(link_shiny),
    nav_item(link_posit)
  )
)

page_navbar()

Finally, page_navbar() provides full-page navigation container similar to navset_underline() but where each nav_panel() is treated as a full page of content and the navigation controls appear in a top-level navigation bar. Note also that the underline styling can be removed via the underline argument.

page_navbar(
  title = "My App",
  bg = "#0062cc",
  underline = TRUE,
  nav_panel(title = "One", p("First tab content.")),
  nav_panel(title = "Two", p("Second tab content.")),
  nav_panel(title = "Three", p("Third tab content")),
  nav_spacer(),
  nav_menu(
    title = "Links",
    align = "right",
    nav_item(link_shiny),
    nav_item(link_posit)
  )
)

bslib documentation built on Sept. 11, 2024, 7:49 p.m.