TextField: TextField

MaskedTextFieldR Documentation

TextField

Description

Text fields (TextField) give people a way to enter and edit text. They’re used in forms, modal dialogs, tables, and other surfaces where text input is required.

For more details and examples visit the official docs. The R package can not handle each and every case, so for advanced use cases you need to work using the original docs to achieve the desired result.

Usage

MaskedTextField(...)

TextField(...)

TextField(...)

TextField.shinyInput(inputId, ..., value = defaultValue)

updateTextField.shinyInput(
  session = shiny::getDefaultReactiveDomain(),
  inputId,
  ...
)

Arguments

...

Props to pass to shiny.react::reactElement. See allowed props listed below in Details section

inputId

Id of the component

value

Value

session

Session

Details

  • ariaLabel string
    Aria label for the text field.

  • autoAdjustHeight boolean
    For multiline text fields, whether or not to auto adjust text field height.

  • autoComplete string
    Whether the input field should have autocomplete enabled. This tells the browser to display options based on earlier typed values. Common values are 'on' and 'off' but for all possible values see the following links: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete#Values https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill

  • borderless boolean
    Whether or not the text field is borderless.

  • className string
    Optional class name that is added to the container of the component.

  • componentRef IRefObject<ITextField>
    Optional callback to access the ITextField component. Use this instead of ref for accessing the public methods and properties of the component.

  • defaultValue string
    Default value of the text field. Only provide this if the text field is an uncontrolled component; otherwise, use the value property.

  • deferredValidationTime number
    Text field will start to validate after users stop typing for deferredValidationTime milliseconds. Updates to this prop will not be respected.

  • description string
    Description displayed below the text field to provide additional details about what text to enter.

  • disabled boolean
    Disabled state of the text field.

  • errorMessage string | JSX.Element
    Static error message displayed below the text field. Use onGetErrorMessage to dynamically change the error message displayed (if any) based on the current value. errorMessage and onGetErrorMessage are mutually exclusive (errorMessage takes precedence).

  • iconProps IIconProps
    Props for an optional icon, displayed in the far right end of the text field.

  • inputClassName string
    Optional class name that is added specifically to the input/textarea element.

  • label string
    Label displayed above the text field (and read by screen readers).

  • mask string
    Only used by MaskedTextField: The masking string that defines the mask's behavior. A backslash will escape any character. Special format characters are: '9': [0-9] 'a': [a-zA-Z] '': [a-zA-Z0-9]

    maskChar string
    Only used by MaskedTextField: The character to show in place of unfilled characters of the mask.

    maskFormat { [key: string]: RegExp; }
    Only used by MaskedTextField: An object defining the format characters and corresponding regexp values. Default format characters: { '9': /[0-9]/, 'a': /[a-zA-Z]/, '': /[a-zA-Z0-9]/ }

  • multiline boolean
    Whether or not the text field is a multiline text field.

  • onChange (event: React.FormEvent<HTMLInputElement | HTMLTextAreaElement>, newValue?: string) => void
    Callback for when the input value changes. This is called on both input and change events. (In a later version, this will probably only be called for the change event.)

  • onGetErrorMessage (value: string) => string | JSX.Element | PromiseLike<string | JSX.Element> | undefined
    Function used to determine whether the input value is valid and get an error message if not. Mutually exclusive with the static string errorMessage (it will take precedence over this).

    When it returns string | JSX.Element: - If valid, it returns empty string. - If invalid, it returns the error message and the text field will show a red border and show an error message below the text field.

    When it returns Promise<string | JSX.Element>: - The resolved value is displayed as the error message. - If rejected, the value is thrown away.

  • onNotifyValidationResult (errorMessage: string | JSX.Element, value: string | undefined) => void
    Function called after validation completes.

  • onRenderDescription IRenderFunction<ITextFieldProps>
    Custom renderer for the description.

  • onRenderLabel IRenderFunction<ITextFieldProps>
    Custom renderer for the label. If you don't call defaultRender, ensure that you give your custom-rendered label an id and that you set the textfield's aria-labelledby prop to that id.

  • onRenderPrefix IRenderFunction<ITextFieldProps>
    Custom render function for prefix.

  • onRenderSuffix IRenderFunction<ITextFieldProps>
    Custom render function for suffix.

  • prefix string
    Prefix displayed before the text field contents. This is not included in the value. Ensure a descriptive label is present to assist screen readers, as the value does not include the prefix.

  • readOnly boolean
    If true, the text field is readonly.

  • resizable boolean
    For multiline text fields, whether or not the field is resizable.

  • styles IStyleFunctionOrObject<ITextFieldStyleProps, ITextFieldStyles>
    Call to provide customized styling that will layer on top of the variant rules.

  • suffix string
    Suffix displayed after the text field contents. This is not included in the value. Ensure a descriptive label is present to assist screen readers, as the value does not include the suffix.

  • theme ITheme
    Theme (provided through customization).

  • underlined boolean
    Whether or not the text field is underlined.

  • validateOnFocusIn boolean
    Run validation when focus moves into the input, and do not validate on change.

    (Unless this prop and/or validateOnFocusOut is set to true, validation will run on every change.)

  • validateOnFocusOut boolean
    Run validation when focus moves out of the input, and do not validate on change.

    (Unless this prop and/or validateOnFocusIn is set to true, validation will run on every change.)

  • validateOnLoad boolean
    Whether validation should run when the input is initially rendered.

  • value string
    Current value of the text field. Only provide this if the text field is a controlled component where you are maintaining its current state; otherwise, use the defaultValue property.

Best practices

Layout

  • Use a multiline text field when long entries are expected.

  • Don't place a text field in the middle of a sentence, because the sentence structure might not make sense in all languages. For example, "Remind me in [textfield] weeks" should instead read, "Remind me in this many weeks: [textfield]".

  • Format the text field for the expected entry. For example, when someone needs to enter a phone number, use an input mask to indicate that three sets of digits should be entered.

Content

  • Include a short label above the text field to communicate what information should be entered. Don't use placeholder text instead of a label. Placeholder text poses a variety of accessibility issues (including possible problems with color/contrast, and people thinking the form input is already filled out).

  • When part of a form, make it clear which fields are required vs. optional. If the input is required, add "(required)" to the label. Don't exclusively use "\*" to indicate required inputs as it is often not read by screen readers. For example, "First name (required)".

  • Use sentence-style capitalization—only capitalize the first word. For more info, see Capitalization in the Microsoft Writing Style Guide.

Examples

library(shiny.fluent)

if (interactive()) {
  shinyApp(
    ui = div(
      TextField.shinyInput("text"),
      textOutput("textValue")
    ),
    server = function(input, output) {
      output$textValue <- renderText({
        sprintf("Value: %s", input$text)
      })
    }
  )
}

Appsilon/shiny.fluent documentation built on June 12, 2022, 2:41 a.m.