Text field API

Import

import { TextField } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

Preview
Code

Name (controlled)

Name (uncontrolled)

import { TextField, Stack } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [name, setName] = useState('Jane Doe');

  return (
    <Stack gap={32}>
      <TextField label="Name (controlled)" value={name} onChange={setName} />
      <TextField label="Name (uncontrolled)" defaultValue="Jane Doe" />
    </Stack>
  );
}

Imperative API

This component exposes an imperative API through the apiRef prop. This API allows triggering behaviors that can’t be expressed by props.

Preview
Code

Name

import { Button, Stack, TextField, type TextFieldApi } from '@cimpress-ui/react';
import { useRef } from 'react';

export default function Demo() {
  const apiRef = useRef<TextFieldApi>(null);

  return (
    <Stack gap={16}>
      <TextField label="Name" defaultValue="Jane Doe" apiRef={apiRef} />

      <Stack gap={16} direction={{ md: 'horizontal' }}>
        <Button onPress={() => apiRef.current?.focus()}>Focus</Button>
        <Button onPress={() => apiRef.current?.select()}>Select contents</Button>
      </Stack>
    </Stack>
  );
}

Accessibility notes

TextField requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

Forms

Text field can integrate with native HTML forms. See our forms guide to learn how to work with forms.

Affixes

TextField supports affixes displayed as part of the input. Affixes can be used for decorative icons or short pieces of text.

Note that affixes are hidden from assistive technologies. It’s up to you to make sure that the input’s purpose is adequately conveyed to screen readers. Note the different values of label and aria-label in the example below:

Preview
Code

Phone number

import { Stack, TextField } from '@cimpress-ui/react';
import { IconEmail } from '@cimpress-ui/react/icons';

export default function Demo() {
  return (
    <Stack gap={16}>
      <TextField label="Phone number" aria-label="A Dutch phone number, without a country code" prefix="+31" />
      <TextField
        label="Email"
        aria-label="Local part of an email in the cimpress.com domain"
        prefix={<IconEmail />}
        suffix="@cimpress.com"
      />
    </Stack>
  );
}

API reference

TextField

Allows users to enter a single line of text with a keyboard.

See text field usage guidelines.

ref Section titled “ ref ” Ref<HTMLDivElement>: The ref type for this component.

TextFieldProps

isClearable Section titled “ isClearable ” boolean: Whether to render a button that can be used to clear the text field.

Defaults to false .
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
label Section titled “ label ” string: The content to display as the label.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
form Section titled “ form ” string: The <form> element to associate the input with. The value of this attribute must be the id of a <form> in the same document. See MDN.
name Section titled “ name ” string: The name of the input element, used when submitting an HTML form. See MDN.
description Section titled “ description ” string: A description for the field. Provides a hint such as specific requirements for what to choose.
error Section titled “ error ” FieldError: An error message for the field.
validate Section titled “ validate ” (value: string) => string | true | string[] | undefined: A function that returns an error message (or true) if a given value is invalid. Validation errors are displayed to the user when the form is submitted. For real-time validation, use the error prop instead.
placeholder Section titled “ placeholder ” string: The placeholder text displayed in the input field.
prefix Section titled “ prefix ” ReactNode: The content displayed at the start of the component. Can be either an icon or a piece of text.
suffix Section titled “ suffix ” ReactNode: The content displayed at the end of the component. Can be either an icon or a piece of text.
apiRef Section titled “ apiRef ” RefObject<TextFieldApi | null>: A React ref that allows access to the imperative API of this component.
autoComplete Section titled “ autoComplete ” string: Describes the type of autocomplete functionality the input should provide if any. See MDN.
maxLength Section titled “ maxLength ” number: The maximum number of characters supported by the input. See MDN.
minLength Section titled “ minLength ” number: The minimum number of characters required by the input. See MDN.
pattern Section titled “ pattern ” string: Regex pattern that the value of the input must match to be valid. See MDN.
type Section titled “ type ” 'search' | (string & ({ })) | 'text' | 'tel' | 'url' | 'email' | 'password': The type of input to render. See MDN.

Defaults to 'text' .
inputMode Section titled “ inputMode ” 'search' | 'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal': Hints at the type of data that might be entered by the user while editing the element or its contents. See MDN.
onKeyDown Section titled “ onKeyDown ” (e: KeyboardEvent) => void: Handler that is called when a key is pressed.
onFocus Section titled “ onFocus ” (e: FocusEvent<HTMLInputElement>) => void: Handler that is called when the element receives focus.
onBlur Section titled “ onBlur ” (e: FocusEvent<HTMLInputElement>) => void: Handler that is called when the element loses focus.
autoFocus Section titled “ autoFocus ” boolean: Whether the element should receive focus on render.
isRequired Section titled “ isRequired ” boolean: Whether user input is required on the input before form submission.
isDisabled Section titled “ isDisabled ” boolean: Whether the input is disabled.
isReadOnly Section titled “ isReadOnly ” boolean: Whether the input can be selected but not changed by the user.
value Section titled “ value ” string: The current value (controlled).
defaultValue Section titled “ defaultValue ” string: The default value (uncontrolled).
onChange Section titled “ onChange ” (value: string) => void: Handler that is called when the value changes.
isInvalid Section titled “ isInvalid ” boolean: Whether the value is invalid.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Text field API

Import

Controlled/uncontrolled usage

Imperative API

Accessibility notes

Forms

Affixes

API reference

TextField

ref

isClearable

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

label

aria-label

aria-labelledby

aria-describedby

aria-details

form

name

description

error

validate

placeholder

prefix

suffix

apiRef

autoComplete

maxLength

minLength

pattern

type

inputMode

onKeyDown

onFocus

onBlur

autoFocus

isRequired

isDisabled

isReadOnly

value

defaultValue

onChange

isInvalid

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft