` element also carries `role="main"` and `tabindex="-1"`, so keyboard focus moves to it when the skip link is activated.
---
## Laying out content
Content goes straight into `gov_main_layout()`. Items stack one below the other, so a page that is just a heading, some text and a table needs no extra layout functions:
```{r, eval = FALSE}
gov_main_layout(
heading_text("Page title", size = "l"),
gov_text("Some introductory text."),
govTable(my_data)
)
```
### A simple text page
For a page that is mostly text, use the standard page width and keep the text to two-thirds of it, as the [GOV.UK layout guidance](https://design-system.service.gov.uk/styles/layout/) recommends for readable line lengths. GOV.UK's `govuk-!-width-two-thirds` class does this without the grid, and goes back to full width on small screens:
```{r, eval = FALSE}
gov_page(
width = "standard",
gov_main_layout(
shiny::tags$div(
class = "govuk-!-width-two-thirds",
heading_text("Cookies", size = "l"),
gov_text("This page explains how we use cookies.")
)
)
)
```
### Columns with `gov_row()` and `gov_box()`
Reach for the grid only when you need **side-by-side columns**, or a section that should sit in a grid column of a set width. It's a two-function system: `gov_row()` holds the columns, and `gov_box()` is each column.
```
gov_main_layout()
└── gov_row()
├── gov_box(size = "two-thirds")
│ └── [your content]
└── gov_box(size = "one-third")
└── [your content]
```
#### `gov_row()`
Creates a GOV.UK grid row. You can have multiple rows inside `gov_main_layout()`, each stacked vertically.
```{r, eval = FALSE}
gov_main_layout(
gov_row(
# columns go here
),
gov_row(
# another row
)
)
```
#### `gov_box()`
Creates a column within a row. The `size` argument controls the column width using GOV.UK Frontend's grid classes:
| `size` | Width |
|---|---|
| `"full"` | 100% |
| `"one-half"` | 50% |
| `"two-thirds"` | 66% |
| `"one-third"` | 33% |
| `"three-quarters"` | 75% |
| `"one-quarter"` | 25% |
Sizes within a row should add up to a full width. For example, `"two-thirds"` and `"one-third"` sit side by side:
```{r, eval = FALSE}
gov_main_layout(
gov_row(
gov_box(
size = "two-thirds",
heading_text("Main content", size = "l"),
# inputs, text, etc.
),
gov_box(
size = "one-third",
heading_text("Sidebar", size = "m"),
# supporting content
)
)
)
```
A single full-width box adds nothing over putting the content directly in `gov_main_layout()`, so leave the grid out in that case.
### `gov_text()`
A wrapper that produces a `` paragraph element. For full guidance on `gov_text()` and all other text functions, see the [Headings and text](headings-and-text.html) vignette.
---
## `gov_layout()` (deprecated)
`gov_layout()` is deprecated as of shinyGovstyle 0.3.0 and will be removed in shinyGovstyle 1.0.0. Use `gov_main_layout()` with `gov_row()` and `gov_box()` instead; the deprecation warning shows how each argument maps across.
---
## Multi-page dashboards
For apps with multiple sections, use `service_navigation()` in combination with a hidden tab panel. The navigation bar renders as a row of links below the header; clicking a link fires a Shiny input that you use in your server to switch the visible panel.
### Setting up navigation links
Pass a named character vector to `service_navigation()`. The names are displayed as link text and the values become the inputIDs:
```{r, eval = FALSE}
service_navigation(
c(
"Summary" = "nav_summary",
"Detailed data" = "nav_detail",
"User guide" = "nav_guide"
)
)
```
If you pass an unnamed vector, the link text is used to make the inputIDs instead.
Either way, every inputID is cleaned up by lowercasing it and replacing non-alphanumeric characters with underscores, so `"Detailed data"` becomes `detailed_data` and `"Nav-Summary"` becomes `nav_summary`. Each link must end up with a unique inputID. `service_navigation_server()`, `navigate_to()`, and `update_service_navigation()` clean up the ids you pass them in the same way, so you can use either form there.
Put `service_navigation()` in your app's top-level UI and wire it up from the top-level server function, not inside a Shiny module. Because of the clean-up, an id wrapped in `ns()` (e.g. `NS("mod", "summary")`) becomes `mod_summary`, which no longer matches the module's namespaced input.
### Wiring navigation to panels
Use a hidden tab panel for the content area. `service_navigation_server()` then wires every nav link to its panel in a single call — no per-link `observeEvent` boilerplate:
```{r, eval = FALSE}
# ui.R — shiny tabsetPanel
shiny::tabsetPanel(
type = "hidden",
id = "main_panels",
shiny::tabPanel("Summary", value = "summary", "Content"),
shiny::tabPanel("Detailed data", value = "detailed_data", "Content"),
shiny::tabPanel("User guide", value = "user_guide", "Content")
)
# server.R — auto-wire the nav links to the panels
shinyGovstyle::service_navigation_server(
session,
tabset_id = "main_panels",
link_to_panel = c(
nav_summary = "summary",
nav_detail = "detailed_data",
nav_guide = "user_guide"
)
)
```
`link_to_panel` is a named character vector — names are nav link inputIds, values are panel values. If your inputIds already match your panel values, pass an unnamed vector instead.
`bslib::navset_hidden()` also responds to `updateTabsetPanel()`, so the same call works whether your tab panel is shiny or bslib.
For navigation that can't be wired declaratively — next / back buttons, modal links, footer shortcuts — use `navigate_to()` to combine the panel switch and the nav-active update in one call:
```{r, eval = FALSE}
# server.R — programmatic navigation in one call
shiny::observeEvent(input$next_btn, {
shinyGovstyle::navigate_to(
session, "main_panels",
inputId = "nav_detail", panel = "detailed_data"
)
})
```
`navigate_to()` defaults to using the nav link `inputId` as the target panel value. Here `nav_detail`'s panel value is `detailed_data` (per the `link_to_panel` mapping above), so pass `panel` explicitly whenever the inputId and panel value differ. See `?navigate_to` for full details.
### Keeping the page title in sync
`service_navigation()` syncs the browser tab title with the active nav link by default, both for link clicks and for programmatic navigation via `update_service_navigation()`. Pass `page_title_suffix` to get the recommended `" | "` format, or `auto_page_title = FALSE` to opt out. For pages where the heading differs from the nav label (or for pages not in the nav), call `update_page_title()` explicitly. See the [Page titles section of the Headings and text vignette](headings-and-text.html#page-titles) for the full rationale and examples.
### Footer-only pages
Some pages — such as an accessibility statement, privacy notice, or cookies information page — should not appear in the service navigation but still need to be reachable. The standard pattern is to add a link in `footer()` and a corresponding hidden tab panel, but to omit the link from `service_navigation()`.
Because the user navigates to these pages outside of the service navigation, there is no active nav item to highlight. You do not need to call `update_service_navigation()` for these transitions. However, you should call it when navigating *back* to a main page from a footer-linked page, so the correct nav item becomes active again.
Footer-only pages also fall outside the `service_navigation()` auto page-title sync — there is no nav link for the JavaScript binding to read. Call `update_page_title()` so the browser tab title reflects the new page:
```{r, eval = FALSE}
# ui.R — footer link, no entry in service_navigation()
footer(
full = TRUE,
links = c(`Accessibility statement` = "accessibility_footer_link")
)
# ui.R — tab panel exists in the hidden tabset but not in service_navigation()
shiny::tabsetPanel(
type = "hidden",
id = "main_panels",
shiny::tabPanel("Summary", value = "nav_summary", "Content"),
shiny::tabPanel("Accessibility statement", value = "accessibility_panel",
"Content")
)
# server.R — navigate to the footer page (no update_service_navigation needed)
shiny::observeEvent(input$accessibility_footer_link, {
shiny::updateTabsetPanel(session, "main_panels",
selected = "accessibility_panel")
shinyGovstyle::update_page_title(
session,
page_title = "Accessibility statement",
service_name = "My dashboard"
)
})
```
### Modularising the code
Once an app has multiple pages, it is strongly recommended to use Shiny modules to keep each page's UI and server logic self-contained. The `inst/example_app` bundled with this package demonstrates this pattern: each page is a module in `inst/example_app/modules/`, with `mod__ui()` and `mod__server()` functions called from the top-level `ui.R` and `server.R`. This keeps individual files focused and makes it straightforward to add or remove pages without touching the overall app structure.
---
## Complete example
The following is a minimal but complete multi-page app that uses all of the layout components covered in this vignette:
```{r, eval = FALSE}
library(shiny)
library(shinyGovstyle)
ui <- gov_page(
title = "Summary | My dashboard",
skip_to_main(),
header(
org_name = "My department",
service_name = "My dashboard"
),
service_navigation(
c(
"Summary" = "nav_summary",
"About" = "nav_about"
),
page_title_suffix = "My dashboard"
),
phase_banner(
inputId = "phase",
type = "Beta",
label = "This is a new service."
),
gov_main_layout(
shiny::tabsetPanel(
type = "hidden",
id = "main_panels",
shiny::tabPanel(
"Summary", value = "nav_summary",
gov_row(
gov_box(
size = "two-thirds",
heading_text("Summary", size = "l"),
gov_text("Welcome to the summary page.")
),
gov_box(
size = "one-third",
heading_text("Quick facts", size = "m"),
gov_text("Supporting information goes here.")
)
)
),
shiny::tabPanel(
"About", value = "nav_about",
# Text-only page: two-thirds keeps it readable even though the
# app itself uses gov_page(width = "full"). See "Content width
# vs page width" above.
shiny::tags$div(
class = "govuk-!-width-two-thirds",
heading_text("About this dashboard", size = "l"),
gov_text("This page describes the dashboard.")
)
),
shiny::tabPanel(
"Accessibility statement", value = "accessibility_panel",
shiny::tags$div(
class = "govuk-!-width-two-thirds",
heading_text("Accessibility statement", size = "l"),
gov_text("This page describes the accessibility of the dashboard.")
)
)
)
),
footer(
links = c(`Accessibility statement` = "accessibility_footer_link")
)
)
server <- function(input, output, session) {
service_navigation_server(
session,
tabset_id = "main_panels",
link_to_panel = c("nav_summary", "nav_about")
)
shiny::observeEvent(input$accessibility_footer_link, {
shiny::updateTabsetPanel(session, "main_panels",
selected = "accessibility_panel")
update_page_title(
session,
page_title = "Accessibility statement",
service_name = "My dashboard"
)
})
}
shiny::shinyApp(ui, server)
```