Skip to contents

A colour picker input that returns a CSS colour string.

Usage

el_color_picker(
  id = NULL,
  value = NULL,
  disabled = FALSE,
  size = NULL,
  show_alpha = FALSE,
  color_format = NULL,
  predefine = NULL,
  popper_class = NULL,
  label = NULL,
  label_position = c("top", "left", "right"),
  label_width = NULL,
  label_suffix = NULL,
  required = FALSE,
  error = NULL,
  show_message = TRUE,
  inline_message = FALSE,
  append_to = NULL,
  aria_label = NULL,
  clearable = NULL,
  empty_values = NULL,
  persistent = NULL,
  popper_style = NULL,
  tabindex = NULL,
  teleported = NULL,
  validate_event = NULL,
  value_on_clear = NULL,
  width = NULL,
  slots = NULL,
  events = NULL,
  on = NULL,
  session = NULL
)

update_el_color_picker(
  session = shiny::getDefaultReactiveDomain(),
  id,
  value = NULL,
  disabled = NULL,
  label = NULL,
  error = NULL,
  size = NULL,
  show_alpha = NULL,
  color_format = NULL,
  predefine = NULL,
  popper_class = NULL,
  append_to = NULL,
  aria_label = NULL,
  clearable = NULL,
  empty_values = NULL,
  persistent = NULL,
  popper_style = NULL,
  tabindex = NULL,
  teleported = NULL,
  validate_event = NULL,
  value_on_clear = NULL
)

Arguments

id

Color picker ID. Auto-generated UUID if NULL.

value

Initial colour value (CSS hex/rgb string). NULL for empty.

disabled

Whether the picker is disabled. Default FALSE.

size

Size: "large", "default" or "small"; NULL follows the form or the page.

show_alpha

Whether to show an alpha channel slider. Default FALSE. When TRUE, the returned value is an rgba(...) string.

color_format

Output format: NULL (auto), "hex", "rgb", "hsv", "hsl".

predefine

Character vector of preset colour swatches. NULL for none.

popper_class

Extra class name for the dropdown panel.

label

A label shown with the component, as Shiny's inputs have: text or a tag. NULL, the default, shows none. It is the component's accessible name too – tied to it with for where the component has a native input that takes the id <id>-input, else with aria-labelledby.

label_position

Where the label sits, as el_form()'s label_position: "top" (the default, as Shiny's labels sit), or beside the component, its text aligned "left" or "right" – which shows once label_width gives the labels a common width.

label_width

Width of a label beside the component, as a CSS unit, so that several line up. Element's label-width.

label_suffix

Text after the label, such as ":". Element's label-suffix.

required

Draw Element's red asterisk before the label. It marks the field; it does not check it – shinyvalidate or el_form() does that.

error

An error message shown under the component in Element's style, the field framed in red. Element's error.

show_message, inline_message

Whether error's message is shown, and whether beside the component rather than under it. Element's show-message and inline-message.

append_to

Which element the color-picker panel appends to. Element Plus's append-to (CSSSelector / HTMLElement).

aria_label

ColorPicker aria-label. Element Plus's aria-label (string).

clearable

Whether to show clear button. Element Plus's clearable (boolean).

empty_values

Empty values of component, see config-provider. Element Plus's empty-values (array).

persistent

When color-picker inactive and persistent is false, the color panel will be destroyed. Element Plus's persistent (boolean).

popper_style

Custom style for ColorPicker's dropdown. Element Plus's popper-style (string / object).

tabindex

ColorPicker tabindex. Element Plus's tabindex (string / number).

teleported

Whether color-picker popper is teleported to the body. Element Plus's teleported (boolean).

validate_event

Whether to trigger form validation. Element Plus's validate-event (boolean).

value_on_clear

Clear return value, see config-provider. Element Plus's value-on-clear (string / number / boolean / Function, or null, which its documentation names): a value as it is, a function as JS(), null as JS("null"). NULL leaves Element's default.

width

Component width, as a CSS unit – "200px", "50%", or a number taken as pixels. Element's own markup carries it, so it behaves like the width argument of a Shiny input.

slots

Named list of Element slot contents, such as list(title = shiny::tags$b("Bold")). A shiny.element component given here is absorbed rather than nested. For a scoped slot, write the template with template().

events

Element's events to report besides those reported unasked, by name: events = "node_drop" reports input$<id>_node_drop. The component's are listed under "Shiny inputs", and by el_events(); a name it does not have is an error.

on

Handlers of your own, for an event not reported or to send something else: a named list of JS() functions, one per event – Element's, or a DOM event with Vue's modifiers ("keyup.enter"). Each is called with report and the event's arguments; report(name, value) sets input$<id>_<name>. See el_widget().

session

In el_color_picker(), deprecated: inside a module, wrap id in ns(), as for any Shiny input; a session given here namespaces id once more, with a warning. In update_el_color_picker(), the Shiny session, the current one by default, as for shiny::updateTextInput().

Value

An htmltools tagList with a Vue-managed color-picker component.

Shiny inputs

InputReportedValue
input$<id>unaskedthe colour
input$<id>_active_changeevents = "active_change"the colour being picked, at most every 200 ms
input$<id>_blurevents = "blur"triggers when Component blurs
input$<id>_clearevents = "clear"triggers when the clear button is clicked
input$<id>_focusevents = "focus"triggers when Component focuses

The same list as el_events("el_color_picker"), which says how an event's arguments travel.

Binding

Every argument can follow v_bind() or v_model() except label, label_position, label_width, label_suffix, required, error, show_message, inline_message (the form item around the component, drawn by R); width (the mount point's style).

Updating from the server

Server-side update for el_color_picker().

Every other argument of el_color_picker() that can change once it is drawn is an argument here too, under the same name. One left NULL stays as it is; NA returns it to Element's default.

update_el_color_picker() is called for its side effect and returns NULL invisibly.

Examples

el_color_picker("cp1", value = "#409EFF")
#> <div id="cp1" data-shiny-vue style="display: contents">
#>   <script type="text/x-template" data-shiny-vue-template><div id="cp1_container" style="display: contents">
#>   <el-color-picker v-bind="$optional(&#39;color-picker&#39;)" v-model="value" :disabled="disabled" :show-alpha="showAlpha" @change="handleChange"></el-color-picker>
#> </div></script>
#>   <script type="application/json" data-shiny-vue-options>{"options":{"data":{"value":"#409EFF","disabled":false,"showAlpha":false,"predefine":null,"size":null,"colorFormat":null,"popperClass":null,"appendTo":null,"ariaLabel":null,"clearable":null,"emptyValues":null,"persistent":null,"popperStyle":null,"tabindex":null,"teleported":null,"validateEvent":null,"valueOnClear":null},"methods":{"handleChange":"function(val) { }"}},"input":"value","rate":null,"type":null,"use":["shinyElement.plugin"],"optional":{"color-picker":{"predefine":"predefine","size":"size","color-format":"colorFormat","popper-class":"popperClass","append-to":"appendTo","aria-label":"ariaLabel","clearable":"clearable","empty-values":"emptyValues","persistent":"persistent","popper-style":"popperStyle","tabindex":"tabindex","teleported":"teleported","validate-event":"validateEvent","value-on-clear":"valueOnClear"}},"evals":["options.methods.handleChange"]}</script>
#> </div>
el_color_picker("cp2", show_alpha = TRUE, predefine = c("#ff4500", "#ff8c00"))
#> <div id="cp2" data-shiny-vue style="display: contents">
#>   <script type="text/x-template" data-shiny-vue-template><div id="cp2_container" style="display: contents">
#>   <el-color-picker v-bind="$optional(&#39;color-picker&#39;)" v-model="value" :disabled="disabled" :show-alpha="showAlpha" @change="handleChange"></el-color-picker>
#> </div></script>
#>   <script type="application/json" data-shiny-vue-options>{"options":{"data":{"value":null,"disabled":false,"showAlpha":true,"predefine":["#ff4500","#ff8c00"],"size":null,"colorFormat":null,"popperClass":null,"appendTo":null,"ariaLabel":null,"clearable":null,"emptyValues":null,"persistent":null,"popperStyle":null,"tabindex":null,"teleported":null,"validateEvent":null,"valueOnClear":null},"methods":{"handleChange":"function(val) { }"}},"input":"value","rate":null,"type":null,"use":["shinyElement.plugin"],"optional":{"color-picker":{"predefine":"predefine","size":"size","color-format":"colorFormat","popper-class":"popperClass","append-to":"appendTo","aria-label":"ariaLabel","clearable":"clearable","empty-values":"emptyValues","persistent":"persistent","popper-style":"popperStyle","tabindex":"tabindex","teleported":"teleported","validate-event":"validateEvent","value-on-clear":"valueOnClear"}},"evals":["options.methods.handleChange"]}</script>
#> </div>
if (interactive()) {
  # inside a server function
  observeEvent(input$go, {
    update_el_color_picker(session, "shade", value = "#67C23A")
  })
}