lab components / Forms and input

Input Field

Enable users to input a single line of text.

Input Field v.s Text area Examples Properties Guidelines

This is a Lab component!

That means it doesn't satisfy our definition of done and may be changed or even deleted. For an exact status, please reach out to the Fancy team through the dev_fancy or ux_fancy channels.

import { InputField } from "@siteimprove/fancylab";

#Input Field v.s Text area

To clarify the differences between InputField and TextArea, a short description is provided.

Component name	Usage	Best practice
Input Field	Capture short, single-line text (max. 1-2 words)	Use for names, email addresses, phone numbers
Text Area	Capture longer, multi-line text	Use for paragraphs, feedback, descriptions, comments

#Examples

Composition:

Label: Provides a clear description of the expected input. See Form Element Wrapper .
Input: The actual text field where users enter data.
Placeholder (optional): Offers a hint or example of the expected input format.
Validation/Error Message (optional): Displays feedback on input validity.
Icon (optional): Enhances visual appeal or provides additional contexts.

#Default

The default input field is the most common variant, suitable for general text input. It adheres to a standard width and height, making it ideal for forms and data-entry tasks.

CodeHTML output

const [value, setValue] = useState("");
return (
	<InputField
		aria-label="My accessible input component"
		placeholder="Placeholder"
		name="some input"
		value={value}
		onChange={setValue}
	/>
);

#Large

The large input field offers a more prominent visual presence, emphasizing its importance or accommodating longer input.

Best Practices:

Consider using the large variant sparingly to avoid overwhelming the user interface.
Ensure that the input field's width remains proportionate to the surrounding content.

CodeHTML output

const [value, setValue] = useState("");

return (
	<InputField
		aria-label="My accessible input component"
		placeholder="Large"
		name="some input"
		value={value}
		onChange={setValue}
		large
	/>
);

#Full width

The full-width input field spans the entire container width, providing maximum space for text input.

Use Cases:

Input fields within dialogs or Modal
Standalone input fields requiring significant visual emphasis

Best Practices:

Reserve full-width input fields for specific scenarios where their size is justified.
Ensure the input field adapts gracefully to different screen sizes.

CodeHTML output

const [value, setValue] = useState("");

return (
	<InputField
		aria-label="My accessible input component"
		placeholder="Full-width"
		name="some input"
		value={value}
		onChange={setValue}
		fullWidth
	/>
);

#Disabled

The disabled input field is visually distinct, indicating that it is not available for interaction.

Use Cases:

Displaying read-only information (e.g., system-generated values)
Preventing input in specific contexts (e.g., when a condition is not met)

Best Practices:

Clearly communicate the reason for the disabled state using a tooltip or accompanying text.
Avoid using disabled input fields for purely aesthetic purposes.

CodeHTML output

const [value, setValue] = useState("");

return (
	<InputField
		aria-label="My accessible input component"
		placeholder="Disabled"
		name="some input"
		value={value}
		onChange={setValue}
		disabled
	/>
);

#Invalid

The invalid input field highlights incorrect or incomplete data, providing immediate feedback to the user.

Use Cases:

Form validation errors (e.g., incorrect email format, required field missing).
Real-time input validation during data entry

Best Practices:

Display a clear and concise error message explaining the issue. See Form Element Wrapper
Allow users to easily correct the input and clear the error.

CodeHTML output

const [value, setValue] = useState("");
return (
	<InputField
		aria-label="My accessible input component"
		placeholder="Placeholder"
		name="some input"
		value={value}
		onChange={setValue}
		invalid
	/>
);

#Slugs

Slug input fields often incorporate symbols like "%" or currency symbols ($) to provide visual cues to the user about the expected input format.

Count:

items

CodeHTML output

const [value1, setValue1] = useState("");
const [value2, setValue2] = useState("");
const [value3, setValue3] = useState("");
const [value4, setValue4] = useState("");
return (
	<>
		<InputFieldWithSlug
			aria-label="My accessible input component"
			placeholder="Placeholder"
			name="some input"
			value={value1}
			onChange={setValue1}
			leftSlug="%"
			fullWidth
		/>
		<br />
		<InputFieldWithSlug
			aria-label="My accessible input component"
			placeholder="Placeholder"
			name="some input"
			value={value2}
			onChange={setValue2}
			leftSlug="Count:"
			rightSlug="items"
			fullWidth
		/>
		<br />
		<InputFieldWithSlug
			aria-label="My accessible input component"
			placeholder="Placeholder"
			name="some input"
			value={value3}
			onChange={setValue3}
			rightSlug="$"
			disabled
			fullWidth
		/>
		<br />
		<InputFieldWithSlug
			aria-label="My accessible input component"
			placeholder="Placeholder"
			name="some input"
			value={value4}
			onChange={setValue4}
			rightSlug="$"
			invalid
			fullWidth
		/>
	</>
);

#Complex Slugs

Complex slug input fields provide additional functionality beyond basic text input, such as:

Search icon only button: Initiates a search based on the entered text.
Select as a filter: Allows users to select the input value as a filter to refine search results or other data sets.

Best Practices:

Present the functionality of the complex slug clearly and intuitively. See Auto Complete.
Use appropriate icons or labels to indicate the available actions.
Provide visual feedback when actions are performed (e.g., loading state during search).
Ensure that the complex slug behavior is consistent with the overall user experience.

CodeHTML output

const [value1, setValue1] = useState("");
const [value2, setValue2] = useState("");
const [value3, setValue3] = useState("");

const dropdownItens = ["Option 1", "Option 2", "Option 3"];
const [selected, setSelected] = useState<string | undefined>(dropdownItens[0]);

return (
	<>
		<InputFieldWithSlug
			aria-label="My accessible input component"
			placeholder="Placeholder"
			name="some input"
			value={value1}
			onChange={setValue1}
			leftSlug={<Button>Slug Button!</Button>}
		/>
		<br />
		<InputFieldWithSlug
			aria-label="My accessible input component"
			placeholder="Placeholder"
			name="some input"
			value={value2}
			onChange={setValue2}
			rightSlug={
				<Button aria-label="Search">
					<Icon>
						<IconSearch />
					</Icon>
				</Button>
			}
		/>
		<br />
		<InputFieldWithSlug
			aria-label="My accessible input component"
			placeholder="Placeholder"
			name="some input"
			value={value3}
			onChange={setValue3}
			leftSlug={
				<Select
					items={dropdownItens.map((x) => ({ value: x, title: x }))}
					value={selected}
					onChange={setSelected}
					hideClearButton
					aria-label="list of 3 options"
				/>
			}
			rightSlug={
				<Button aria-label="Search">
					<Icon>
						<IconSearch />
					</Icon>
				</Button>
			}
		/>
	</>
);

When using the type="date" property, the input will be rendered with a date picker, using the browser's native implementation. This means that the input can be rendered differently depending on the browser. The input value will be a string in the format YYYY-MM-DD, which is the default format for the native date picker, but the date presentation will be according to the browser's locale setting.

Use Cases:

Forms requiring date input (e.g., birth date, event date).
Calendars or scheduling features.
Filtering data by date.

Best Practices:

Use a clear label to indicate the expected date format (e.g., YYYY-MM-DD).
Consider providing additional input validation to ensure the entered date is valid.

CodeHTML output

const [value, setValue] = useState("2023-12-31");
return (
	<InputField
		aria-label="My accessible date input"
		name="mydate"
		type="date"
		value={value}
		onChange={setValue}
	/>
);

#Properties

CodePropsHTML output

Property	Description	Defined	Value
valueRequired	`string`Value of the form control	YesNo
onChangeRequired	`function`Callback for onChange event	YesNo
nameOptional	`string`Name applied to the form control	YesNo
idOptional	`string`Id applied to the form control	YesNo
invalidOptional	`boolean`Is the form control invalid	YesNo	truefalse
onBlurOptional	`function`Callback for onBlur event	YesNo
aria-labelOptional	`string`Label of the form control	YesNo
aria-describedbyOptional	`string`ID of an an element that describes what the form control is for	YesNo
aria-labelledbyOptional	`string`ID of an an element that labels this form control	YesNo
placeholderOptional	`string`	YesNo
maxLengthOptional	`number`	YesNo
disabledOptional	`boolean`	YesNo	truefalse
typeOptional	`"color" \| "date" \| "email" \| "number" \| "password" \| "search" \| "text"`	YesNo
inputModeOptional	`"decimal" \| "email" \| "numeric" \| "search" \| "tel" \| "url"`	YesNo
autoCompleteOptional	`string`	YesNo
largeOptional	`boolean`	YesNo	truefalse
fullWidthOptional	`boolean`	YesNo	truefalse
widthOptional	`number`	YesNo
autoFocusOptional	`boolean`	YesNo	truefalse
roleOptional	`string`	YesNo
classNameOptional	`string`Custom className that's applied to the outermost element (only intended for special cases)	YesNo
styleOptional	`object`Style object to apply custom inline styles (only intended for special cases)	YesNo
tabIndexOptional	`number`Tab index of the outermost HTML element of the component	YesNo
onKeyDownOptional	`function`Callback for onKeyDown event	YesNo
onMouseDownOptional	`function`Callback for onMouseDown event	YesNo
onMouseEnterOptional	`function`Callback for onMouseEnter event	YesNo
onMouseLeaveOptional	`function`Callback for onMouseLeave event	YesNo
onFocusOptional	`function`Callback for onFocus event	YesNo
data-componentOptional	`string`Name of the component. Should only be set by components since it needs to stable. Used to track component usage	YesNo
data-observe-keyOptional	`string`Unique string, used by external script e.g. for event tracking	YesNo

You need to collect a single line of text input from the user.
The input can be of various types, including text, email, number, date, etc.
You require a simple and standardized way to gather user information.

#Placement

InputField is typically used in the following places:

Form: For collecting user data, such as names, email addresses, phone numbers, etc.
Search: To allow users to enter search queries.
Data entry tables: For inline editing of cell values.
Modal: To gather input within a focused context.

#Style

Siteimprove Design System: Adhere to Siteimprove's guidelines for color, typography, and spacing. If you are not using a component from Fancy, match the styling of your InputField to existing components for visual consistency.
Responsive Field Widths:
- Field widths should be proportionate to the expected content length, typically allowing for the average input to fit comfortably. Align field widths with the responsive grid system (columns or percentages) to maintain layout consistency.
- On smaller screens, prioritize usability by using full-width fields. This prevents users from having to scroll horizontally to input information.
Clear Labels & Placeholders:
- Labels: Use clear, concise labels placed above the field to identify its purpose. Ensure sufficient contrast between the label and the background for readability.
- Placeholders (optional): Use placeholders within the field to provide hints or examples of the expected input format.
Input Masking & Validation:
- Input masking: For specific formats (e.g., phone numbers, usage with dates), use input masking to guide users and ensure correct input.
- Real-time validation: Provide immediate feedback on input validity (e.g., error messages) to help users correct mistakes quickly. See Form Element Wrapper.
Graceful Text Handling:
- Input overflow: If the input exceeds the visible field length, either allow horizontal scrolling or use an ellipsis (...) to indicate that there is more content.
- Label wrapping: If a label is too long to fit on a single line, allow it to wrap naturally to the next line to maintain readability.