File field ​

a text field is an input field that users can type into. It has a range of options and supports several text formats including numbers.

Usage ​

Use to allow users to upload files.

<script lang="ts" setup>
import { FileField } from '@returnless/focus-ui';
</script>

<template>
  <FileField label="Upload your file" name="file" v-model="fileInput" type="file" accept="image" />
</template>

Multiple files ​

Use to allow users to upload multiple files. The multiple prop should be set to true.

<script lang="ts" setup>
import { FileField } from '@returnless/focus-ui';
</script>

<template>
  <FileField label="Upload your file" name="file" multiple v-model="multipleFileInput" type="file" accept="image" />
</template>

Best practices ​

Text fields should:

• Be clearly labeled, so it's obvious to users what they should enter into a field.
• Be labeled as "Optional" when you need to request input that's not request.
• Only ask for information that's really needed.
• Validate input as soon as users have finished interacting with a field (but not before).

Autocomplete ​

The autocomplete attribute in an input field controls two types of browser behaviour:

1. Browser autofill: a feature that automatically populates form fields with previously-saved information, such as passwords, addresses, and credit card data.

• Autofill is an important feature for users. Google has found that users complete forms 30% faster when using autofill.
• The WHATWG has a list of supported autofill values for the autocomplete attribute. Review the section "4.10. 18.7 Autofill for all the input types and their corresponding autocomplete attribute values.

2. Browser autocomplete: a feature that displays previously submitted values for that field.

• When this is on for a field, a user is presented with a list of previously submitted values for the input.

Always add an autocomplete attribute and value to inputs if the type is: color, date, datetime-local, email, month, number, password, range, search, tel, text, time, url, or week.

Turning autofill/autocomplete off ​

Even if you do not want the browser to autofill a user's information, it is recommended you still have an autocomplete attribute with the value "off" or "nope".

Unfortunately, not all browsers support or respect autocomplete="off". This makes things challenging. Chrome, for example, has a long outstanding bug and won't add support for "off" for now.

Chrome does seem to turn autocomplete off when using the value nope (or any non-valid string). However, we have seen some inconsistencies even with that support.

Content guidelines ​

Text fields can be grouped in a form or placed individually in the UI. Placeholder text should generally be avoided in text fields. Help text can be used below the text input area to guide the user on acceptable inputs.

Field labels ​

Field labels act as a title for the text field. Labels should typically be short and in noun form. For example, "Name".

Placeholder text ​

In general, avoid using placeholder text in text fields. It can pose a range of accessibility problems, like:

• Low color contrast, making the text hard to read.
• Inconsistent behaviour between browsers and screen readers.
• Text disappearing when the user starts typing, which can be confusing to people with cognitive impairments.
• Limited space available for additional content, due to field size.

Exception: read the guidelines on [search fields].

Help text ​

Help text provides extra guidance or instructions to people filling out a form field. It and also be used to clarify how the information will be used.

Use help text:

• When the text field label doesn't clearly explain the purpose of the text input.
• To provide guidance or instructions on the type of information needed.
• To show examples of the required format for modeled text inputs.

Best practices for help text:

• Avoid repeating the field label. If the field label provides sufficient context for completing the action, then you likely don't need to add help text.
• If there's not enough room to include both instructions and an example, then only include the example.

Text input types ​

There are three types of text inputs:

1. Modeled text inputs: These are fields that require a specific format to be valid. They're often used for tags, dates, and some tracking numbers. Modeled text is highly structured, so providing examples is useful.
2. Free text inputs: These are fields that accept short strings of text. They're often used for SKU's, barcodes, and titles. Only provide example text if you know how the text should be structured, such as a tracking number of discount code.
3. Multiline text inputs: These are fields that are rendered as multiline textarea elements, as well as text input elements that accept long strings of text. They're often used for product descriptions, order comments, and customer notes. Users can write whatever they want, so providing example text is less useful.

Modeled text inputs ​

Modeled text inputs are text field inputs that require text to be formatted in a specific way. For instance, tags need to be separated by commas, and dates need to be typed in YYYY-MM-DD format. Because modeled text inputs require a particular structure, always include examples that demonstrate how the user should enter the information.

• Use help text to include an instructional call to action and an example that shows the required text format.
• If there's not enough room to include both an instructional call to action and an example, then include only the example.
• Use the word "Example" followed by a colon to introduce the example.

Free text inputs ​

Free text inputs accept a single string of text, without any particular structure. Use the field label to clearly indicate what should go in the text field.

Don't provide an example for free text inputs. The text doesn't follow a specific format, and we shouldn't assume what belongs in the field. If more context is needed, use help text.

Avoid redundancy ​

If a text field label has a call to action, there's no need to repeat it in the help text. Instead, add a sentence that provides extra context.

For example, when a free text input is located independent of a form and has no surrounding context, you can make the field label a call to action.

Point in the right direction ​

If the text field label isn't clear about where the user can find the information, use help text to guide them.

Titles, names, and descriptions ​

Don't use placeholder text for free input titles, names, and descriptions; use help text instead.

Codes and tracking numbers ​

Don't use placeholder text for codes or tracking numbers; use help text instead. If the code follows a standardized format, include an example, using the same format as help text for modeled content. If not, omit the example since the field's content can vary.

Choose clear names for the field label, and don't repeat it in the help text if possible. Instead, offer context that will help the user understand and complete the task quickly.

Multiline text inputs ​

Multiline fields let users type long blocks of text. There are a few different versions:

• Plain textarea elements with no formatting options.
• Formatted textarea elements with what-you-see-is-what-you-get (WYSIWYG) menus.
• Plain text input elements that accept long strings of text.
• Plain text input elements that accept long strings of text and expand as the user types.

Multiline inputs hold things like product and collection descriptions, notes about an order, and anything else the user wants to type into them.

We usually don't know what will go in multiline fields, so providing example text isn't helpful. Instead, include help text that explains how the text will be used and who can view it.

Accessibility ​

Structure ​

Screen readers convey information about text fields automatically through native HTML.

• Use the disabled prop to add the HTML disabled attribute to the text field.
• Use the readOnly prop to add the HTML readonly attribute to the text field.
• If you use the type prop, then some assistive technologies will adept the software keyboard to the current task. This helps users with mobility, vision, and cognitive issues to enter information more easily.

Use the id prop to provide a unique id attribute value for the text field. If you don't provide an id, then the component generates one automatically. All text fields need to have unique id values.

Labeling ​

The label prop is required to convey the purpose of the checkbox to all users.

If there are separate visual cues that convey the purpose of the text field to sighted users, then the label can be visually hidden with the labelHidden prop.

When you provide help text via the helpText prop or an inline error message via the error prop, the help or error content is conveyed to screen reader users with the aria-describedby attribute. This attribute causes the content to be read along with the label, either immediately or after a short delay.

Use the placeholder prop to provide additional instructions. However, don't rely on placeholders alon since the content isn't always conveyed.

Keyboard support ​

Text fields have standard keyboard support.

• Users who rely on the keyboard expect to move focus to each text field using the tab key (or shift + tab when tabbing backwards).
• If the type is set to number, then users can use the up and down arrow keys to adjust the value typed into the field when hovering over or focusing the field to make the arrows appear.
• Using the disabled prop will prevent the text field from receiving focus, and users won't be able to interact with it using the keyboard.
• The readOnly prop allows focus on the text field but prevents input or editing.

Automatically focusing ​

Although you can use the autoFocus prop to automatically move focus to the text field, it's generally best to avoid focusing on fields automatically. The autoFocus prop is set to false by default and should only be used in cases where it won't force focus to skip other controls or content of equal or greater importance.