diff --git a/docs/inputs/text.md b/docs/inputs/text.md index 915840bcd..adf49368f 100644 --- a/docs/inputs/text.md +++ b/docs/inputs/text.md @@ -1,8 +1,6 @@ # Text input -[API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#text) - -The text input allows freeform single-line text entry. (For multiple lines, see the [text area](./textarea)) input. +API · Source · The text input allows freeform single-line text entry. For multiple lines, see the [text area](./textarea) 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. @@ -17,7 +15,13 @@ text We recommend providing a *label* and *placeholder* to improve usability. You can also supply an initial *value* if desired. ```js echo -const name = view(Inputs.text({label: "Name", placeholder: "Enter your name", value: "Anonymous"})); +const name = view( + Inputs.text({ + label: "Name", + placeholder: "Enter your name", + value: "Anonymous" + }) +); ``` ```js echo @@ -27,7 +31,12 @@ name The *label* may be either a text string or an HTML element, if more control over styling is desired. ```js echo -const signature = view(Inputs.text({label: html`Fancy`, placeholder: "What’s your fancy?"})); +const signature = view( + Inputs.text({ + label: html`Fancy`, + 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](https://developer.mozilla.org/en-US/docs/Learn/Forms/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. @@ -40,20 +49,18 @@ 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”). You can also check whether the current value is valid by calling [*form*.checkValidity](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#dom-cva-checkvalidity). - -```js echo -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). ```js echo @@ -74,7 +81,7 @@ 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) + datalist: capitals.map((d) => d.State) })); ``` @@ -98,24 +105,24 @@ fixed The available text input options are: -* *label* - a label; either a string or an HTML element. -* *type* - the [input type](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types), such as “password” or “email”; defaults to “text”. -* *value* - the initial value; defaults to the empty string. -* *placeholder* - the [placeholder](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/placeholder) attribute. -* *spellcheck* - whether to activate the browser’s spell-checker. -* *autocomplete* - the [autocomplete](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) attribute, as text or boolean (true for on, false for off). -* *autocapitalize* - the [autocapitalize](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autocapitalize) attribute, as text or boolean (true for on, false for off). -* *pattern* - the [pattern](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern) attribute. -* *minlength* - [minimum length](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/minlength) attribute. -* *maxlength* - [maximum length](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength) attribute. -* *min* - [minimum value](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/min) attribute; formatted appropriately, *e.g.* yyyy-mm-dd for the date type. -* *max* - [maximum value](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/max) 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 before updating; 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](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#dom-cva-checkvalidity) is used. While the input is not considered valid, changes to the input will not be reported. \ No newline at end of file +* *label* - a label; either a string or an HTML element +* *type* - the [input type](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types), such as “password” or “email”; defaults to “text” +* *value* - the initial value; defaults to the empty string +* *placeholder* - the [placeholder](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/placeholder) attribute +* *spellcheck* - whether to activate the browser’s spell-checker +* *autocomplete* - the [autocomplete](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) attribute, as text or boolean +* *autocapitalize* - the [autocapitalize](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/autocapitalize) attribute, as text or boolean +* *pattern* - the [pattern](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern) attribute +* *minlength* - [minimum length](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/minlength) attribute +* *maxlength* - [maximum length](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/maxlength) attribute +* *min* - [minimum value](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/min) attribute (`YYYY-MM-DD` for the date type) +* *max* - [maximum value](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/max) 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](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#dom-cva-checkvalidity) is used. While the input is not considered valid, changes to the input will not be reported.