diff --git a/NEWS.md b/NEWS.md
index 4a8d10068..80718350d 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -6,7 +6,7 @@
Related to the above change, `navset_bar()` now defaults to using `underline = TRUE` so that both `page_navbar()` and `navset_bar()` use the same set of default `navbar_options()`.
- In `navbar_options()`, `inverse` is replaced by `theme`, which takes values `"light"` (dark text on a **light** background), `"dark"` (light text on a **dark** background), or `"auto"` (follow page settings). (#1146)
+ In `navbar_options()`, `inverse` is replaced by `theme`, which takes values `"light"` (dark text on a **light** background), `"dark"` (light text on a **dark** background), or `"auto"` (follow page settings, the default). This change affects that default navbar foreground and background colors for Bootswatch preset themes with Bootstrap 5. Detailed instructions for customizing the navbar appearance, especially for Bootswatch themes, can be found in `?navbar_options`. (#1146)
## New features
diff --git a/R/navbar_options.R b/R/navbar_options.R
index 6ab9253d9..aa13e6062 100644
--- a/R/navbar_options.R
+++ b/R/navbar_options.R
@@ -5,7 +5,82 @@
#' This helper should be used to create the list of options expected by
#' `navbar_options` in [page_navbar()] and [navset_bar()].
#'
-#' ## Changelog
+#' ## Navbar style with Bootstrap 5 and Bootswatch themes
+#'
+#' In \pkg{bslib} v0.9.0, the default navbar colors for Bootswatch themes with
+#' Bootstrap 5 changed. Prior to v0.9.0, bslib pre-selected navbar background
+#' colors in light and dark mode; after v0.9.0 the default navbar colors are
+#' less opinionated by default and follow light or dark mode (see
+#' [input_dark_mode()]).
+#'
+#' You can use `navbar_options()` to adjust the colors of the navbar when using
+#' a Bootswatch preset theme with Bootstrap 5. For example, the [Bootswatch
+#' documentation for the Flatly theme](https://bootswatch.com/flatly/) shows
+#' 4 navbar variations. Inspecting the source code for the first example reveals
+#' the following markup:
+#'
+#' ```html
+#'
+#' ```
+#'
+#' Note that this navbar uses the `bg-primary` class for a dark navy background.
+#' The navbar's white text is controlled by the `data-bs-theme="dark"`
+#' attribute, which is used by Bootstrap for light text on a _dark_ background.
+#' In \pkg{bslib}, you can achieve this look with:
+#'
+#' ```r
+#' ui <- page_navbar(
+#' theme = bs_theme(5, "flatly"),
+#' navbar_options = navbar_options(class = "bg-primary", theme = "dark")
+#' )
+#' ```
+#'
+#' This particular combination of `class = "bg-primary"` and `theme = "dark"`
+#' works well for most Bootswatch presets.
+#'
+#' Another variation from the Flatly documentation features a navar with dark
+#' text on a light background:
+#'
+#' ```r
+#' ui <- page_navbar(
+#' theme = bs_theme(5, "flatly"),
+#' navbar_options = navbar_options(class = "bg-light", theme = "light")
+#' )
+#' ```
+#'
+#' The above options set navbar foreground and background colors that are always
+#' the same in both light and dark modes. To customize the navbar colors used in
+#' light or dark mode, you can use the `$navbar-light-bg` and `$navbar-dark-bg`
+#' Sass variables. When provided, bslib will automatically choose to use
+#' light or dark text as the foreground color.
+#'
+#' ```r
+#' ui <- page_navbar(
+#' theme = bs_theme(
+#' 5,
+#' preset = "flatly",
+#' navbar_light_bg = "#18BC9C", # flatly's success color (teal)
+#' navbar_dark_bg = "#2C3E50" # flatly's primary color (navy)
+#' )
+#' )
+#' ```
+#'
+#' Finally, you can also use the `$navbar-bg` Sass variable to set the navbar
+#' background color for both light and dark modes:
+#'
+#' ```r
+#' ui <- page_navbar(
+#' theme = bs_theme(
+#' 5,
+#' preset = "flatly",
+#' navbar_bg = "#E74C3C" # flatly's danger color (red)
+#' )
+#' )
+#' ```
+#'
+#' @section Changelog:
#'
#' This function was introduced in \pkg{bslib} v0.9.0, replacing the `position`,
#' `bg`, `inverse`, `collapsible` and `underline` arguments of [page_navbar()]
diff --git a/man/navbar_options.Rd b/man/navbar_options.Rd
index c9a60c55d..fc8e26a5a 100644
--- a/man/navbar_options.Rd
+++ b/man/navbar_options.Rd
@@ -48,7 +48,78 @@ This helper should be used to create the list of options expected by
\code{navbar_options} in \code{\link[=page_navbar]{page_navbar()}} and \code{\link[=navset_bar]{navset_bar()}}.
}
\details{
-\subsection{Changelog}{
+\subsection{Navbar style with Bootstrap 5 and Bootswatch themes}{
+
+In \pkg{bslib} v0.9.0, the default navbar colors for Bootswatch themes with
+Bootstrap 5 changed. Prior to v0.9.0, bslib pre-selected navbar background
+colors in light and dark mode; after v0.9.0 the default navbar colors are
+less opinionated by default and follow light or dark mode (see
+\code{\link[=input_dark_mode]{input_dark_mode()}}).
+
+You can use \code{navbar_options()} to adjust the colors of the navbar when using
+a Bootswatch preset theme with Bootstrap 5. For example, the \href{https://bootswatch.com/flatly/}{Bootswatch documentation for the Flatly theme} shows
+4 navbar variations. Inspecting the source code for the first example reveals
+the following markup:
+
+\if{html}{\out{
}}\preformatted{
+}\if{html}{\out{
}}
+
+Note that this navbar uses the \code{bg-primary} class for a dark navy background.
+The navbar's white text is controlled by the \code{data-bs-theme="dark"}
+attribute, which is used by Bootstrap for light text on a \emph{dark} background.
+In \pkg{bslib}, you can achieve this look with:
+
+\if{html}{\out{
}}
+
+This particular combination of \code{class = "bg-primary"} and \code{theme = "dark"}
+works well for most Bootswatch presets.
+
+Another variation from the Flatly documentation features a navar with dark
+text on a light background:
+
+\if{html}{\out{
}}
+
+The above options set navbar foreground and background colors that are always
+the same in both light and dark modes. To customize the navbar colors used in
+light or dark mode, you can use the \verb{$navbar-light-bg} and \verb{$navbar-dark-bg}
+Sass variables. When provided, bslib will automatically choose to use
+light or dark text as the foreground color.
+
+\if{html}{\out{
}}
+
+Finally, you can also use the \verb{$navbar-bg} Sass variable to set the navbar
+background color for both light and dark modes:
+
+\if{html}{\out{
}}
+}
+}
+\section{Changelog}{
+
This function was introduced in \pkg{bslib} v0.9.0, replacing the \code{position},
\code{bg}, \code{inverse}, \code{collapsible} and \code{underline} arguments of \code{\link[=page_navbar]{page_navbar()}}
@@ -57,7 +128,7 @@ removed in a future version of \pkg{bslib}. Note that the deprecated
\code{inverse} argument of \code{\link[=page_navbar]{page_navbar()}} and \code{\link[=navset_bar]{navset_bar()}} was replaced with
the \code{theme} argument of \code{navbar_options()}.
}
-}
+
\examples{
navbar_options(position = "static-top", bg = "#2e9f7d", underline = FALSE)