% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bs-theme.R
\name{bs_theme}
\alias{bs_theme}
\alias{bs_theme_update}
\alias{is_bs_theme}
\title{Create a Bootstrap theme}
\usage{
bs_theme(
  version = version_default(),
  preset = NULL,
  ...,
  brand = NULL,
  bg = NULL,
  fg = NULL,
  primary = NULL,
  secondary = NULL,
  success = NULL,
  info = NULL,
  warning = NULL,
  danger = NULL,
  base_font = NULL,
  code_font = NULL,
  heading_font = NULL,
  font_scale = NULL,
  bootswatch = NULL
)

bs_theme_update(
  theme,
  ...,
  preset = NULL,
  bg = NULL,
  fg = NULL,
  primary = NULL,
  secondary = NULL,
  success = NULL,
  info = NULL,
  warning = NULL,
  danger = NULL,
  base_font = NULL,
  code_font = NULL,
  heading_font = NULL,
  font_scale = NULL,
  bootswatch = NULL
)

is_bs_theme(x)
}
\arguments{
\item{version}{The major version of Bootstrap to use (see \code{\link[=versions]{versions()}}
for possible values). Defaults to the currently recommended version
for new projects (currently Bootstrap 5).}

\item{preset}{The name of a theme preset, either a built-in theme provided by
bslib or a Bootswatch theme (see \code{\link[=builtin_themes]{builtin_themes()}} and
\code{\link[=bootswatch_themes]{bootswatch_themes()}} for possible values). This argument takes precedence
over the \code{bootswatch} argument and only one \code{preset} or \code{bootswatch} can be
provided. When no \code{bootswatch} theme is specified, and \code{version} is 5 or
higher, \code{preset} defaults to \code{"shiny"}. To remove the \code{"shiny"} preset,
provide a value of \code{"bootstrap"} (this value will also work in
\code{bs_theme_update()} to remove a \code{preset} or \code{bootswatch} theme).}

\item{...}{arguments passed along to \code{\link[=bs_add_variables]{bs_add_variables()}}.}

\item{brand}{Specifies how to apply branding to your theme using
\href{https://posit-dev.github.io/brand-yml/}{brand.yml}, a simple YAML file that
defines key brand elements like colors, fonts, and logos. Valid options:
\itemize{
\item \code{NULL} (default): Automatically looks for a \verb{_brand.yml} file in the
current directory or in \verb{_brand/} or \verb{brand/} in the current directory.
If not found, it searches parent project directories for a \verb{_brand.yml}
file (also possibly in \verb{_brand/} or \verb{brand/}). If a \verb{_brand.yml} file is
found, it is applied to the Bootstrap theme.
\item \code{TRUE} (default): Automatically looks for a \verb{_brand.yml} file in the
current or app directory as described above. If a \verb{_brand.yml} file
\emph{is not found}, \code{bs_theme()} will throw an error.
\item \code{FALSE}: Disables any brand.yml usage, even if a \verb{_brand.yml} file is
present.
\item A file path that directly points to a specific brand.yml file (with any
file name) that you want to use.
\item Use a list to directly provide brand settings directly in R, following
the brand.yml structure.
}

Learn more about creating and using brand.yml files at the
\href{https://posit-dev.github.io/brand-yml/}{brand.yml homepage} or run
\code{shiny::runExample("brand.yml", package = "bslib")} to try brand.yml in a
demo app.}

\item{bg}{A color string for the background.}

\item{fg}{A color string for the foreground.}

\item{primary}{A color to be used for hyperlinks, to indicate primary/default
actions, and to show active selection state in some Bootstrap components.
Generally a bold, saturated color that contrasts with the theme's base
colors.}

\item{secondary}{A color for components and messages that don't need to stand
out. (Not supported in Bootstrap 3.)}

\item{success}{A color for messages that indicate an operation has succeeded.
Typically green.}

\item{info}{A color for messages that are informative but not critical.
Typically a shade of blue-green.}

\item{warning}{A color for warning messages. Typically yellow.}

\item{danger}{A color for errors. Typically red.}

\item{base_font}{The default typeface.}

\item{code_font}{The typeface to be used for code. Be sure this is monospace!}

\item{heading_font}{The typeface to be used for heading elements.}

\item{font_scale}{A scalar multiplier to apply to the base font size. For
example, a value of \code{1.5} scales font sizes to 150\% and a value of \code{0.8}
scales to 80\%. Must be a positive number.}

\item{bootswatch}{The name of a bootswatch theme (see \code{\link[=bootswatch_themes]{bootswatch_themes()}}
for possible values). When provided to \code{bs_theme_update()}, any previous
Bootswatch theme is first removed before the new one is applied (use
\code{bootswatch = "bootstrap"} to effectively remove the Bootswatch theme).}

\item{theme}{A \code{\link[=bs_theme]{bs_theme()}} object.}

\item{x}{an object.}
}
\value{
Returns a \code{\link[sass:sass_layer]{sass::sass_bundle()}} (list-like) object.
}
\description{
Creates a Bootstrap theme object, where you can:
\itemize{
\item Choose a (major) Bootstrap \code{version}.
\item Choose a \href{https://bootswatch.com}{Bootswatch theme} (optional).
\item Customize main colors and fonts via explicitly named arguments (e.g.,
\code{bg}, \code{fg}, \code{primary}, etc).
\item Customize other, lower-level, Bootstrap Sass variable defaults via \code{...}.
}

To learn more about how to implement custom themes, as well as how to use
them inside Shiny and R Markdown, \href{https://rstudio.github.io/bslib/articles/theming.html}{see here}.
}
\section{Colors}{


Colors may be provided in any format that \code{\link[htmltools:parseCssColors]{htmltools::parseCssColors()}} can
understand. To control the vast majority of the ('grayscale') color
defaults, specify both the \code{fg} (foreground) and \code{bg} (background) colors.
The \code{primary} and \code{secondary} theme colors are also useful for accenting the
main grayscale colors in things like hyperlinks, tabset panels, and buttons.
}

\section{Fonts}{


Use \code{base_font}, \code{code_font}, and \code{heading_font} to control the main
typefaces. These arguments set new defaults for the relevant \code{font-family}
CSS properties, but don't necessarily import the relevant font files. To
both set CSS properties \emph{and} import font files, consider using the various
\code{\link[=font_face]{font_face()}} helpers.

Each \verb{*_font} argument may be a single font or a \code{font_collection()}.
A font can be created with \code{\link[=font_google]{font_google()}}, \code{\link[=font_link]{font_link()}}, or \code{\link[=font_face]{font_face()}},
or it can be a character vector of font names in the following format:
\itemize{
\item A single unquoted name (e.g., \code{"Source Sans Pro"}).
\item A single quoted name (e.g., \code{"'Source Sans Pro'"}).
\item A comma-separated list of names w/ individual names quoted as necessary.
(e.g. \code{c("Open Sans", "'Source Sans Pro'", "'Helvetica Neue', Helvetica, sans-serif")})
}

\code{font_google()} sets \code{local = TRUE} by default, which ensures that the font
files are downloaded from \href{https://fonts.google.com/}{Google Fonts} when
your document or app is rendered. This guarantees that the client has access
to the font family, making it relatively safe to specify just one font
family:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{bs_theme(base_font = font_google("Pacifico", local = TRUE))
}\if{html}{\out{</div>}}

That said, we recommend you specify multiple "fallback" font families,
especially when relying on remote and/or system fonts being available.
Fallback fonts are useful not only for handling missing fonts, but also
ensure that your users don't experience a Flash of Invisible Text (FOIT)
which can be quite noticeable with remote web fonts on a slow internet
connection.

\if{html}{\out{<div class="sourceCode r">}}\preformatted{bs_theme(base_font = font_collection(font_google("Pacifico", local = FALSE), "Roboto", "sans-serif"))
}\if{html}{\out{</div>}}
}

\examples{
\dontshow{if (rlang::is_interactive()) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf}

theme <- bs_theme(
  # Controls the default grayscale palette
  bg = "#202123", fg = "#B8BCC2",
  # Controls the accent (e.g., hyperlink, button, etc) colors
  primary = "#EA80FC", secondary = "#48DAC6",
  base_font = c("Grandstander", "sans-serif"),
  code_font = c("Courier", "monospace"),
  heading_font = "'Helvetica Neue', Helvetica, sans-serif",
  # Can also add lower-level customization
  "input-border-color" = "#EA80FC"
)

bs_theme_preview(theme)

# Lower-level bs_add_*() functions allow you to work more
# directly with the underlying Sass code
theme <- bs_add_variables(theme, "my-class-color" = "red")
theme <- bs_add_rules(theme, ".my-class { color: $my-class-color }")
\dontshow{\}) # examplesIf}
}
\references{
\itemize{
\item \href{https://rstudio.github.io/bslib/articles/theming/index.html}{Get Started: Theming}
introduces theming with bslib in Shiny apps and R Markdown documents.
\item \href{https://rstudio.github.io/bslib/articles/bs5-variables/index.html}{Theming: Bootstrap 5 variables}
provides a searchable reference of all theming variables available in
Bootstrap 5.
\item \href{https://rstudio.github.io/bslib/articles/custom-components/index.html}{Theming: Custom components}
gives a tutorial on creating a dynamically themable custom component.
\item bslib's theming capabilities are powered by
\href{https://rstudio.github.io/sass/}{the {sass} package}.
\item \href{https://rstudio.github.io/bslib/articles/utility-classes/index.html}{Bootstrap's utility classes}
can be helpful when you want to change the appearance of an element
without writing CSS or customizing your \code{bs_theme()}.
}
}
\seealso{
Other Bootstrap theme functions: 
\code{\link{bs_add_variables}()},
\code{\link{bs_current_theme}()},
\code{\link{bs_dependency}()},
\code{\link{bs_global_theme}()},
\code{\link{bs_remove}()},
\code{\link{bs_theme_dependencies}()},
\code{\link{bs_theme_preview}()}
}
\concept{Bootstrap theme functions}
