--- title: "Input" slug: input category: component type: documentation version: 20.0.0 tokens: 3231 source: https://ovh.github.io/design-system/v20.0.0/llms/react-components-input--documentation.txt --- # Input _**Input** component is an **Input** field where users can type into_ ## Overview Form Guidelines] } figmaLink="https://www.figma.com/design/9jDDTcR4a9jPRFcdjawAlf/ODS---UI-Kit?node-id=93-22570" githubUrl="https://github.com/ovh/design-system/tree/master/packages/ods-react/src/components/input" name="Input"> An **Input** is used to allow the user to enter a single line information in a field. | | | |---|---| | Name | undefined | | Also known as | Text Input, Text Field | ## Usage An **Input** is used to type a free-form short text in a field. It is often used within a Form Field component that adds its label. It is commonly used in a form, such as asking the user their name or email address, data entered can be text or numbers. The **Input** component can be used in addition with an **Autocomplete**. ### Dos & Don'ts **Do** - Always pair the Input with a clear and explicit label, using the Form Field component for example - Provide a helper message or validation feedback below the Input when appropriate (e.g., expected format or error state) - Use the clearable button option when it helps users reset the field quickly and efficiently - Use the toggle mask button for sensitive inputs to let users show or hide the content - Include a search button within the Input if a specific action is expected (e.g., triggering a search) - Choose the appropriate input type (email, password, search, etc.) to support native validation - Use start or end content for a unit, a currency symbol or a fixed part of the value, so the user does not have to type it **Don't** - Don't use an Input for multi-line content, use a Textarea instead - Don't use an Input when users must choose from a predefined set of answers. Prefer Select, Combobox, or Radio - Don't leave an Input without a label - Don't overload the Input with multiple embedded actions (e.g., clear + search + toggle) since it creates visual clutter - Don't use an Input that is inappropriately sized for its content - Don't rely on start or end content to convey the field's purpose: it complements the label, it does not replace it - Don't give start or end content its own background or border, and don't make it taller than the field ### Best Practices in Context 1. **Input** 2. **Placeholder or input text** 3. **Clearable button** - optional 4. **Start content** - optional content before the value 5. **End content** - optional content after the value ## Placement **Input** should be vertically aligned with other form components on a same page. **Inputs** that are strongly related in a form can be grouped. This group can flow horizontally left to right and/or vertically top to bottom. ## Behavior **Inputs** can be hovered, focused and clicked / triggered. They can be disabled or readonly as well. The user can start typing in the **Input** after clicking or focusing on the field container. A clearable button can be displayed within the **Input** to clear its content. This button becomes visible as soon as the user types the first character and removes all content when clicked. A toggle mask button can be displayed within the **Input** to toggle the visibility of its content, such as revealing or hiding a password in a masked input. A search button can be displayed within the **Input** to trigger a specific action, such as performing a search. Content can be placed inside the field, before the value with `startContent` and after it with `endContent`. This content is never part of the value: the user cannot edit it, it does not appear in `value` or `onChange`, and it is not submitted with the form. Any node is accepted, within the constraints described below. Typical cases include a unit such as `kg` or `%`, a currency symbol, a fixed part of the value such as a domain extension, an icon, or a small ghost button. When to reach for it is covered in **Dos & Don'ts** above. Both are placed with logical directions, so they follow the writing direction rather than a fixed side. The built-in action buttons always stay at the far end of the field, after the end content, so they remain at the same distance from the border whether or not decoration is present. The content must fit within the field's content height, so that it never makes the **Input** taller, and must not carry a background or a border of its own. Use `size="xs"` for a `Button`, the size the built-in actions use. For a control with its own surface adjoined to the field, such as a country selector or a calendar trigger, compose elements around the **Input** instead; see **Datepicker** and **Phone Number**. The **Input** does not disable, hide or otherwise alter the content it is given. When the content holds a control, pass that control its own `disabled` alongside the field's. ## Content Adornments ```tsx <> ``` ## Content Adornments with Button ```tsx ) } /> ``` ## Navigation ### Focus Management The **Input** field receives focus as part of the natural tab order. If a clear button is present, it becomes focusable immediately after the **Input** field. If a toggle mask button (show/hide password) is present, it becomes focusable after the clear button. If a search button is present, it becomes focusable after the other **Input** action buttons. If `startContent` or `endContent` holds a focusable element, it takes its natural place in the tab order: start content before the field, end content after the field and before the action buttons. If the **Input** field is read-only, it can still receive focus but cannot be edited. If the **Input** is disabled, it is skipped in the tab order and cannot be edited. ### General Keyboard Shortcuts Pressing `Tab` moves focus forward. Pressing `Shift` + `Tab` moves focus backward to the previous interactive element. Typing any character while the **Input** field is focused enters text into the field. Pressing `Backspace` deletes the character preceding the cursor. Pressing `Enter` while a clear, toggle mask, or search button is focused triggers the corresponding action. ## Accessibility To ensure proper accessibility, the **Input** component must be correctly labeled and provide meaningful context when interactive elements (such as icon buttons) are used. ### Always provide an explicit label Every **Input** must have a clear and explicit label to ensure that users (especially screen reader users) understand its purpose, using either **FormField** or a native label tag. ```tsx Name: ``` Screen readers will announce the label, the field and its content. ### Make start & end content audible The **Input** does not describe `startContent` or `endContent` for you: it never alters `aria-describedby`, so whatever you or the surrounding **FormField** put there is what screen readers announce. Content that carries meaning, such as a unit, a currency or a fixed part of the value, is therefore silent unless you reference it. Give it an id and point the field at it: ```tsx Weight: kg } /> ``` Screen readers will announce the label, the field, its content and the unit. Only reference the parts that describe the value. A control inside the decoration announces itself when focus reaches it, and its action label must not become guidance about what to type: ```tsx kg } /> ``` Note that a value passed to `aria-describedby` **replaces** the one the **FormField** would supply, so include the helper and error ids yourself if you still need them. ### Override action context To provide more context on the interactive elements, you can provide your own custom translations to the component. ```tsx Search: ``` Screen readers will announce the label, the field, its content and custom label of focused action. ## Login Form ```tsx { const [email, setEmail] = useState(''); const [password, setPassword] = useState(''); const [errors, setErrors] = useState<{ email?: string, password?: string }>({}); // `noValidate` hands validation over to the form: the browser never blocks the submit, // so the errors below are the only ones the user ever sees. function onSubmit(event: FormEvent): void { event.preventDefault(); setErrors({ email: email.length === 0 ? 'Enter the email address of the account admin.' : undefined, password: password.length < 12 ? 'This password is too short.' : undefined, }); } return (
Admin email ) => setEmail(event.target.value) } placeholder="you@example.com" startContent={ } type={ INPUT_TYPE.email } value={ email } /> { errors.email } Root password ) => setPassword(event.target.value) } value={ password } /> At least 12 characters. { errors.password }
); } ``` ## Domain Availability Search ```tsx { const takenAddresses = ['admin', 'api', 'www']; const [address, setAddress] = useState(''); const [isChecking, setIsChecking] = useState(false); const [isTaken, setIsTaken] = useState(false); const checkTimer = useRef | undefined>(undefined); useEffect(() => () => clearTimeout(checkTimer.current), []); function onAddressChange(e: ChangeEvent): void { const value = e.target.value; const isLongEnough = value.length > 2; clearTimeout(checkTimer.current); setAddress(value); setIsTaken(false); setIsChecking(isLongEnough); if (isLongEnough) { checkTimer.current = setTimeout(() => { setIsChecking(false); setIsTaken(takenAddresses.includes(value.toLowerCase())); }, 700); } } return ( Public address Type at least 3 characters to check availability - "api" is already taken. This address is already taken. ); } ```