Text input

API · Source · The text input allows freeform single-line text entry. For multiple lines, see the text area input.

In its most basic form, a text input is a blank box whose value is the empty string. The text’s value changes as the user types into the box.

const text = view(Inputs.text());

text

We recommend providing a label and placeholder to improve usability. You can also supply an initial value if desired.

const name = view(
  Inputs.text({
    label: "Name",
    placeholder: "Enter your name",
    value: "Anonymous"
  })
);

name

The label may be either a text string or an HTML element, if more control over styling is desired.

const signature = view(
  Inputs.text({
    label: html`<b>Fancy</b>`,
    placeholder: "What’s your fancy?"
  })
);

For specific classes of text, such as email addresses and telephone numbers, you can supply one of the HTML5 input types, such as email, tel (for a telephone number), or url, as the type option. Or, use a convenience method: Inputs.email, Inputs.password, Inputs.tel, or Inputs.url.

const password = view(Inputs.password({label: "Password", value: "open sesame"}));

password

The HTML5 pattern, spellcheck, minlength, and maxlength options are also supported. If the user enters invalid input, the browser may display a warning (e.g., “Enter an email address”).

const email = view(
  Inputs.text({
    type: "email",
    label: "Email",
    placeholder: "Enter your email"
  })
);

If the input will trigger some expensive calculation, such as fetching from a remote server, the submit option can be used to defer the text input from reporting the new value until the user clicks the Submit button or hits Enter. The value of submit can also be the desired contents of the submit button (a string or HTML).

const query = view(Inputs.text({label: "Query", placeholder: "Search", submit: true}));

query

To provide a recommended set of values, pass an array of strings as the datalist option. For example, the input below is intended to accept the name of a U.S. state; you can either type the state name by hand or click one of the suggestions on focus.

const capitals = FileAttachment("us-state-capitals.tsv").tsv({typed: true});

const state = view(Inputs.text({
  label: "U.S. state",
  placeholder: "Enter state name",
  datalist: capitals.map((d) => d.State)
}));

state

To prevent a text input’s value from being changed, use the disabled option.

const fixed = view(Inputs.text({label: "Fixed value", value: "Can’t edit me!", disabled: true}));

fixed

Options

Inputs.text(options)

The available text input options are:

• label - a label; either a string or an HTML element
• type - the input type, such as “password” or “email”; defaults to “text”
• value - the initial value; defaults to the empty string
• placeholder - the placeholder attribute
• spellcheck - whether to activate the browser’s spell-checker
• autocomplete - the autocomplete attribute, as text or boolean
• autocapitalize - the autocapitalize attribute, as text or boolean
• pattern - the pattern attribute
• minlength - minimum length attribute
• maxlength - maximum length attribute
• min - minimum value attribute (YYYY-MM-DD for the date type)
• max - maximum value attribute
• required - if true, the input must be non-empty; defaults to minlength > 0
• validate - a function to check whether the text input is valid
• width - the width of the input (not including the label)
• submit - whether to require explicit submission; defaults to false
• datalist - an iterable of suggested values
• readonly - whether input is readonly; defaults to false
• disabled - whether input is disabled; defaults to false

If validate is not defined, text.checkValidity is used. While the input is not considered valid, changes to the input will not be reported.