Input

Input can have a placeholder, a default (initial) value, a label and a description. Label can be required or optional as well.

<Form>
	<Form.Group widths="equal">
		<Form.Input
			label="First Name"
			placeholder="Leia"
			defaultValue="Leia"
			required
		/>
		<Form.Input label="Last Name" placeholder="Organa" required />
	</Form.Group>
	<Form.Group grouped>
		<Form.Input label="Address" placeholder="1834 Tantive Ave" />
		<Form.Input width="3" label="Age" />
	</Form.Group>
</Form>

States

Input can provide a visual representations of its status with disabled, error, readonly and loading states. You can use any combination of those states for the experience.

Default

<Form>
	<Form.Input label="Default Input" defaultValue="Leia" />
	<Form.Input label="Empty input" />
	<Form.Input label="Placeholder Input" placeholder="Leia" />
	<Form.Input label="Required Input" defaultValue="Leia" required />
	<Form.Input label="Input" description="Description goes here..." />
</Form>

Disabled

<Form>
	<Form.Input label="Default Input" defaultValue="Leia" disabled />
	<Form.Input label="Empty Input" disabled />
	<Form.Input label="Placeholder Input" placeholder="Leia" disabled />
	<Form.Input label="Required Input" defaultValue="Leia" required disabled />
</Form>

Error

<Form>
	<Form.Input label="Default Input" defaultValue="Leia" error />
	<Form.Input label="Empty Input" error />
	<Form.Input label="Placeholder Input" placeholder="Leia" error />
	<Form.Input label="Required Input" defaultValue="Leia" required error />
	<Form.Input
		label="Required Input"
		required
		error="This field cannot be left blank."
	/>
</Form>

Readonly

<Form>
	<Form.Input label="Default Input" defaultValue="Leia" readOnly />
	<Form.Input label="Empty Input" readOnly />
	<Form.Input label="Placeholder Input" placeholder="Leia" readOnly />
	<Form.Input label="Required Input" defaultValue="Leia" required readOnly />
</Form>

Loading

<Form>
	<Form.Input label="Default Input" defaultValue="Leia" loading />
	<Form.Input label="Empty Input" loading />
	<Form.Input label="Placeholder Input" placeholder="Leia" loading />
</Form>

Label, Counter, and Placeholder

Labels should be used to describe the information we're asking the user to give us. Placeholders should be used to show an example of the content we're asking the user for. If we use placeholders as labels, once the user starts typing into the field, they lose the description of what we're asking for.

<Form>
	<Form.Input label="First Name" placeholder="Leia" />
	<Form.Input label="Phone Number" placeholder="(800) 555-1234" />
</Form>

<Form>
	<Form.Input label="" placeholder="First Name" />
	<Form.Input label="" placeholder="Phone Number" />
</Form>

Label Help

Labels can have a help icon with a tooltip to provide additional context to a label.

<Form>
	<Form.Input
		label="Input Label"
		labelProps={{
			help: 'This is help text',
		}}
	/>
</Form>

Required and Optional

A visual indicator can be applied on a Input's label.

<Form>
	<Form.Input
		label="Required Label"
		labelProps={{
			required: true,
		}}
	/>
	<Form.Input
		label="Optional Label"
		labelProps={{
			optional: true,
		}}
	/>
</Form>

Counter

Counter can be displayed when there is a maxLength.

<Form>
	<Form.Input label="Counter Example" maxLength={20} showCounter />
</Form>

Action

Input action can be used to combine a text input with an action button, making them visually merged into a single block.

<Form>
	<Form.Group widths="5">
		<Form.Input
			label="Search"
			action={<Button iconName="search" />}
			small
		/>
	</Form.Group>
	<Form.Group widths="4">
		<Form.Input label="Set Job Duration" action="Set" />
	</Form.Group>
	<Form.Group widths="3">
		<Form.Input label="Add Technician" action="Add" large />
	</Form.Group>
</Form>

Addons

Input addons can be used to show an icon or a text that help users enter information in the Input. These serve as decorative additions, not additional actions.

<Form>
	<Form.Group widths="5">
		<Form.Input label="Cost" shortLabel="$" small />
	</Form.Group>
	<Form.Group widths="4">
		<Form.Input
			label="Job Duration"
			shortLabel="days"
			shortLabelPosition="right"
		/>
	</Form.Group>
	<Form.Group widths="3">
		<Form.Input
			label="Technician Name"
			shortLabel={<Icon name="person" />}
			large
		/>
	</Form.Group>
</Form>

Addon Guidance

Addons are helpful when they enhance the understanding of an input. This can be particularly useful with units of measurement, where fields may have specific formats, and with icons that are universally understood.

Addons should be avoided when they don't serve a use for users or when the addon's meaning is not well understood. A good default is to design without an addon, and only adding one to further enhance its usability.

<Form>
	<Form.Group widths="2">
		<Form.Input
			label="New Business Unit"
			shortLabel={<Icon name="public" />}
		/>
	</Form.Group>

	<Form.Group widths="5">
		<Form.Input label="ZIP Code" shortLabel={<Icon name="place" />} />
	</Form.Group>

	<Form.Group widths="1">
		<Form.Input label="Post Title" shortLabel={<Icon name="tag" />} />
	</Form.Group>
</Form>

Sizes

Inputs can appear in three different sizes. The medium size is the default size, while small and large will allow the inputs to resize to take up more and less space in a layout. These match up with our Button sizes.

<Form>
	<Form.Input label="Small Input" small />
	<Form.Input label="Default Input" />
	<Form.Input label="Large Input" large />
</Form>

Focus

An input can be focused via a ref

() => {
	const ref = React.createRef();
	const onClick = () => {
		ref.current.focus();
	};

	return (
		<Form>
			<Stack spacing="1">
				<Button onClick={onClick}>Focus</Button>
				<Input ref={ref} style={{ flexGrow: 1 }} />
			</Stack>
		</Form>
	);
};

Best Practices

Inputs should:

• Be clearly labeled so it’s obvious to the user what they should enter into the field
• Only ask for information that’s really needed
• Validate input as soon as merchant has finished interacting with a field (but not before)

Content Guidelines

Use a label for all input fields

A label is a short, meaningful description that clearly indicates what the user is expected to enter. Labels should be 1 to 3 words and written in title case. Labels should primarily be nouns. Avoid using labels as CTAs. A label is not inline help and shouldn’t be used to provide instruction.

Follow capitalization rules

Input labels should be written in title case.

Avoid using placeholder text

Placeholder text has several accessibility issues:

• Text has low contrast which makes the text hard to read
• Text disappears as soon as the user starts typing
• Can’t accommodate additional context due to limited space
• Unreliable for screen readers

Use inline help to provide hints, formatting, and requirements.

Placeholders in Form Fields Are Harmful (Nielsen Norman Group)

Show hints, formatting, and requirements

Inline help should explain a feature or the outcome of the actions the user is about to take.

The description should adapt to the situation and context. The guidance could be focused on what is needed, or it could describe how to enter it.

• An overall description of the input field
• Hints for what kind of information needs to be input
• Specific formatting examples or requirements

Do not repeat the label in order to prompt someone to interact with it.

Don’t add inline help when unneeded or solely to make it match other inputs that have inline help text.

Use sentence case, and only include period if more than one sentence is used.

Follow the inline help content guidelines.

Keep overlay help short, simple, and scannable

Overlay help should be short and easily scannable, no longer than a single phrase or short sentence.

Avoid repeating the UI text. Use sentence case, and only include period if more than one sentence is used.

For more complex or important information, consider another method of presentation, e.g., inline help or a link to the knowledge base.

Related Content

Components

• To build a full form, use the Form component.
• For multiline text input, use a TextArea.

Patterns

• Form design pattern for how related controls are ordered.

Importing

import { Input } from '@servicetitan/design-system';