Docs: Clarify update*Input() selected behavior with NULL (#2144)#4397
Open
samuelbharti wants to merge 1 commit into
Open
Docs: Clarify update*Input() selected behavior with NULL (#2144)#4397samuelbharti wants to merge 1 commit into
samuelbharti wants to merge 1 commit into
Conversation
The shared update-input template claimed that "Any arguments with NULL values will be ignored", which contradicted the behavior of `selected` for choice-based inputs: when `choices` is also updated, `selected = NULL` resets the selection rather than preserving it. Soften the shared template to a generic, accurate statement and add per-argument `selected` documentation to updateSelectInput(), updateCheckboxGroupInput(), and updateRadioButtons() describing how `NULL`, `character(0)`, and an explicit value behave.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates Shiny’s documentation to resolve contradictions around update*Input() handling of NULL arguments, with a focus on clarifying how selected = NULL behaves for choice-based inputs when options are re-rendered.
Changes:
- Generalized the shared
update*Input()docs to sayNULLarguments are generally ignored, with per-argument exceptions. - Added/updated
selectedargument documentation forupdateSelectInput()/updateSelectizeInput()/updateVarSelectInput(),updateCheckboxGroupInput(), andupdateRadioButtons(). - Added a NEWS entry describing the documentation clarification.
Reviewed changes
Copilot reviewed 3 out of 14 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| R/update-input.R | Adds per-argument selected documentation for choice-based update*Input() functions. |
| man-roxygen/update-input.R | Updates shared updater template wording about NULL handling. |
| NEWS.md | Notes the documentation clarification for selected semantics. |
| man/updateSelectInput.Rd | Updates selected argument and shared updater details text for select updaters. |
| man/updateCheckboxGroupInput.Rd | Updates selected argument and shared updater details text for checkbox group updater. |
| man/updateRadioButtons.Rd | Updates selected argument and shared updater details text for radio updater. |
| man/updateTextInput.Rd | Regenerated to reflect updated shared template wording. |
| man/updateTextAreaInput.Rd | Regenerated to reflect updated shared template wording. |
| man/updateSliderInput.Rd | Regenerated to reflect updated shared template wording. |
| man/updateNumericInput.Rd | Regenerated to reflect updated shared template wording. |
| man/updateDateInput.Rd | Regenerated to reflect updated shared template wording. |
| man/updateDateRangeInput.Rd | Regenerated to reflect updated shared template wording. |
| man/updateCheckboxInput.Rd | Regenerated to reflect updated shared template wording. |
| man/updateActionButton.Rd | Regenerated to reflect updated shared template wording. |
Files not reviewed (11)
- man/updateActionButton.Rd: Language not supported
- man/updateCheckboxGroupInput.Rd: Language not supported
- man/updateCheckboxInput.Rd: Language not supported
- man/updateDateInput.Rd: Language not supported
- man/updateDateRangeInput.Rd: Language not supported
- man/updateNumericInput.Rd: Language not supported
- man/updateRadioButtons.Rd: Language not supported
- man/updateSelectInput.Rd: Language not supported
- man/updateSliderInput.Rd: Language not supported
- man/updateTextAreaInput.Rd: Language not supported
- man/updateTextInput.Rd: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+528
to
+530
| #' To preserve the current selection across a `choices` update, pass | ||
| #' `selected = input$id` explicitly. To clear the selection, pass | ||
| #' `selected = character(0)`. |
Comment on lines
+584
to
+586
| #' first choice. To preserve the current selection across a `choices` update, | ||
| #' pass `selected = input$id` explicitly. To start with no item selected, | ||
| #' pass `selected = character(0)`. |
Comment on lines
+639
to
+645
| #' does not preserve the current selection when the set of options is also | ||
| #' being updated (via `choices`, or `data` for the `varSelect` variants): the | ||
| #' options are re-rendered with none selected, except for server-side | ||
| #' single-select `updateSelectizeInput()`, which selects the first option. To | ||
| #' preserve the current selection across such an update, pass | ||
| #' `selected = input$id` explicitly. To clear the selection, pass | ||
| #' `selected = character(0)`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #2144
Summary
updateSelectInput()'s documentation was self-contradicting. The sharedman-roxygen/update-input.Rtemplate stated that "Any arguments with NULL values will be ignored; they will not result in any changes to the input object on the client", but for choice-based inputsselected = NULL(the default) does not preserve the current selection — whenchoicesis also being updated, the options are re-rendered with nothing selected. The inheritedselectedparam doc also carriedselectInput()'s constructor wording ("defaults to the first value..."), which is misleading for an updater.This is a docs-only change with no behavior change. It generalizes the shared template so its first paragraph is accurate for all
update*Input()functions ("Arguments withNULLvalues are generally ignored... See the per-argument documentation for any exceptions."). The previous wording namedselected/choice-inputs in the shared template, which leaked an irrelevant sentence onto unrelated functions (updateSliderInput(),updateTextInput(), etc.) that have noselectedargument. It then adds per-argumentselecteddocumentation toupdateSelectInput()(shared via@rdnamewith the selectize/varSelect variants),updateCheckboxGroupInput(), andupdateRadioButtons(), describing howNULL(no-op unless options are also updated),character(0)(clears the selection), and an explicit value behave, plus the server-side single-select selectize and radio "first choice" caveats.All behavioral claims were verified against the actual
sendInputMessage()payloads using a mock session.Verification
The documented contract, confirmed by inspecting the message sent to the client via a mock session:
selected = NULL, nochoicesupdate -> empty message (no-op, selection preserved)selected = NULL, withchoices-> options re-rendered, none selectedselected = character(0), nochoices->value = character(0)(selection cleared)updateRadioButtons(selected = NULL, choices = ...)-> first choice selectedRendered help pages:
?updateSelectInputnow describes updater semantics forselected;?updateSliderInput(and other non-choice updaters) show only the clean generic paragraph with no strayselectedreference.