Build Shiny Module
Create reusable Shiny UI/server module pairs with proper namespace isolation, reactive communication, and composability.
When to Use
- Extracting a reusable component from a growing Shiny app
- Building a UI widget that will be used in multiple places
- Encapsulating complex reactive logic behind a clean interface
- Composing larger applications from smaller, testable units
Inputs
- Required: Module purpose and functionality description
- Required: Input/output contract (what the module receives and returns)
- Optional: Whether the module nests other modules (default: no)
- Optional: Framework context (golem, rhino, or vanilla)
Procedure
Step 1: Define the Module Interface
Before writing code, define what the module accepts and returns:
Module: data_filter
Inputs: reactive dataset, column names to filter on
Outputs: reactive filtered dataset
UI: filter controls (selectInput, sliderInput, dateRangeInput)
Expected: Clear contract specifying reactive inputs, reactive outputs, and UI elements.
On failure: If the interface is unclear, the module is probably too broad. Split it into smaller modules with single responsibilities.
Step 2: Create the Module UI Function
#' Data Filter Module UI
#'
#' @param id Module namespace ID
#' @return A tagList of filter controls
#' @export
dataFilterUI <- function(id) {
ns <- NS(id)
tagList(
selectInput(
ns("column"),
"Filter column",
choices = NULL
),
uiOutput(ns("filter_control")),
actionButton(ns("apply"), "Apply Filter", class = "btn-primary")
)
}
Key rules:
- Function name follows
<name>UI convention
- First argument is always
id
- Create
ns <- NS(id) at the top
- Wrap every
inputId and outputId with ns()
- Return a
tagList() to allow flexible placement
Expected: UI function that creates namespaced input/output elements.
On failure: If IDs collide when using the module twice, check that every ID is wrapped with ns(). Common miss: IDs inside renderUI() or uiOutput() — these need ns() too.
Step 3: Create the Module Server Function
#' Data Filter Module Server
#'
#' @param id Module namespace ID
#' @param data Reactive expression returning a data frame
#' @param columns Character vector of filterable column names
#' @return Reactive expression returning the filtered data frame
#' @export
dataFilterServer <- function(id, data, columns) {
moduleServer(id, function(input, output, session) {
ns <- session$ns
# Update column choices when data changes
observeEvent(data(), {
available <- intersect(columns, names(data()))
updateSelectInput(session, "column", choices = available)
})
# Dynamic filter control based on selected column
output$filter_control <- renderUI({
req(input$column)
col_data <- data()[[input$column]]
if (is.numeric(col_data)) {
sliderInput(
ns("value_range"),
"Range",
min = min(col_data, na.rm = TRUE),
max = max(col_data, na.rm = TRUE),
value = range(col_data, na.rm = TRUE)
)
} else {
selectInput(
ns("value_select"),
"Values",
choices = unique(col_data),
multiple = TRUE,
selected = unique(col_data)
)
}
})
# Return filtered data as a reactive
filtered <- eventReactive(input$apply, {
req(input$column)
col <- input$column
df <- data()
if (is.numeric(df[[col]])) {
req(input$value_range)
df[df[[col]] >= input$value_range[1] &
df[[col]] <= input$value_range[2], ]
} else {
req(input$value_select)
df[df[[col]] %in% input$value_select, ]
}
}, ignoreNULL = FALSE)
return(filtered)
})
}
Key rules:
- Function name follows
<name>Server convention
- First argument is always
id
- Additional arguments are reactive expressions or static values
- Use
moduleServer(id, function(input, output, session) { ... })
- Use
session$ns for dynamic UI created inside the server
- Return reactive values explicitly
Expected: Server function that processes inputs and returns reactive output.
On failure: If reactive values don't update, check that inputs from dynamic UI use session$ns (not the outer ns). If the module returns NULL, ensure return() is the last expression inside moduleServer().
Step 4: Wire the Module into the Parent App
# In app_ui.R or ui
ui <- page_sidebar(
title = "Analysis App",
sidebar = sidebar(
dataFilterUI("filter1")
),
card(
DT::dataTableOutput("table")
)
)
# In app_server.R or server
server <- function(input, output, session) {
# Raw data source
raw_data <- reactive({ mtcars })
# Call module — capture its return value
filtered_data <- dataFilterServer(
"filter1",
data = raw_data,
columns = c("cyl", "mpg", "hp", "wt")
)
# Use the module's returned reactive
output$table <- DT::renderDataTable({
filtered_data()
})
}
Expected: Module appears in the UI and its returned reactive flows into downstream outputs.
On failure: If the module UI doesn't render, verify the id string matches between UI and server calls. If the returned reactive is NULL, check that the server function actually returns a value.
Sibling modules communicate through the parent, not directly with each other. Capture the first module's returned reactive and pass it as an argument into the second module's server call — filtered_data <- dataFilterServer("filter1", data = raw_data, columns = cols), then summaryServer("summary1", data = filtered_data). Pass the reactive itself, not filtered_data(): the receiving module has to re-run when the value changes, so it needs the reactive, not whatever value it happened to hold at the moment of the call. Reactive expressions are the most portable format for moving reactive information between modules — a module that takes a plain reactive argument works under any parent that can produce one.
Step 5: Compose Nested Modules (Optional)
For modules that contain other modules:
analysisUI <- function(id) {
ns <- NS(id)
tagList(
dataFilterUI(ns("filter")),
plotOutput(ns("plot"))
)
}
analysisServer <- function(id, data) {
moduleServer(id, function(input, output, session) {
# Call inner module with namespaced ID
filtered <- dataFilterServer("filter", data = data, columns = names(data()))
output$plot <- renderPlot({
req(filtered())
plot(filtered())
})
return(filtered)
})
}
Key rule: In the UI, nest with ns("inner_id"). In the server, call with just "inner_id" — moduleServer handles the namespace chaining.
Expected: Inner module renders correctly within the outer module's namespace.
On failure: If the inner module's UI doesn't appear, you likely forgot ns() around the inner module's ID in the outer UI function. If server communication breaks, check that the inner module ID matches (no ns() in the server call).
Step 6: Test the Module in Isolation
# Quick test app for the module
if (interactive()) {
shiny::shinyApp(
ui = fluidPage(
dataFilterUI("test"),
DT::dataTableOutput("result")
),
server = function(input, output, session) {
data <- reactive(iris)
filtered <- dataFilterServer("test", data, names(iris))
output$result <- DT::renderDataTable(filtered())
}
)
}
Expected: Module works correctly in the minimal test app.
On failure: If the module fails in isolation but works in the full app (or vice versa), check for implicit dependencies on global variables or parent session state.
Validation
Common Pitfalls
- Forgetting
ns() in renderUI(): Dynamic UI created inside the server must use session$ns — the outer ns is not available inside moduleServer().
- Passing non-reactive data: Module arguments that change over time must be reactive expressions. Pass
reactive(data) not data.
- ID mismatch: The
id string in the UI call must exactly match the id in the server call.
- Not returning reactives: If the module computes something the parent needs, it must
return() a reactive. Forgetting this is a silent bug.
- Namespace in nested modules: In UI:
ns("inner_id"). In server: just "inner_id". Mixing these up causes namespace double-wrapping or missing prefixes.
Related Skills
scaffold-shiny-app — set up the app structure before adding modulestest-shiny-app — test modules with testServer() unit testsdesign-shiny-ui — bslib layout and theming for module UIsoptimize-shiny-performance — cache and async patterns within modules