Note TextField extends props from HTMLInputElement on web. On mobile, it extends TextInputProps from react-native.
Default composition of Inputs.
<TextInput
label="API Access Token"
placeholder="HaeJiWplJohn6W42eCq0Qqft0"
end={
<Box paddingX={2}>
<Link variant="caption" color="primary" to="">
COPY
</Link>
</Box>
}
/>
Sizes
size accepts s, m, and l. Defaults to l.
<VStack gap={3}>
<TextInput label="Small (s)" placeholder="Small" size="s" />
<TextInput label="Medium (m)" placeholder="Medium" size="m" />
<TextInput label="Large (l) — default" placeholder="Large" size="l" />
</VStack>
Accessible Text Inputs
TextInput comes with an accessibilityLabel prop. If no accessibilityLabel is passed, it will use the label as the accessibilityLabel. If you want an accessibilityLabel that differs from the Label, you can set this prop.
Here, since no accessibilityLabel is passed, the accessibilityLabel will be "Email".
<TextInput label="Email" />
Example of passing an accessibilityLabel. For web, this will set aria-label="Enter a Coinbase Email" under the hood
<TextInput accessibilityLabel="Enter a Coinbase Email" label="Email" />
Accessibility tipLike any component system, much of the responsibility for building accessible UIs is in your hands as the consumer to properly implement the component composition. We'll do our best to provide sane fallbacks, but here are the biggest gotchas for TextInputs you can watch out for.
aria-* attr overrides
Any time you use variant='negative', we assume you're showing an error state. If for some reason this is not the case, you will want to use aria-invalid={false} to override the default configuration.
It's also advised you always format helperText with Error: ${errorMessage}. We'd do that for you, but i18n isn't baked into CDS. Take a look at the example below:
<VStack gap={4}>
<TextInput
label="Text Input rendered in an errored state"
placeholder="Enter a color"
helperText="Error: Your favorite color is not orange"
variant="negative"
/>
<TextInput
label="Text Input that's red but not in an errored state"
placeholder="Enter a color"
helperText="You like red?"
variant="negative"
aria-invalid={false}
/>
</VStack>
Placeholder Text
<TextInput label="Label" placeholder="Placeholder" />
Borderless
For borderless TextInput usage, prefer adding a focus border with focusedBorderWidth.
If you need a fully borderless input (including focus), use that pattern with a TypeAhead
composition.
<VStack gap={2} padding={2}>
<TextInput
label="Borderless TextInput"
placeholder="placeholder"
helperText="When bordered is false, focus border styling is disabled by default."
bordered={false}
/>
<TextInput
label="Borderless TextInput (with focus border)"
placeholder="placeholder"
helperText="Set focusedBorderWidth to opt into a focus border style."
bordered={false}
focusedBorderWidth={200}
/>
</VStack>
Helper Text
Default Sentiment
<VStack gap={3}>
<VStack>
<Text as="p" font="headline">
Default sentiment
</Text>
<TextInput
label="Campaign title"
placeholder="Title"
helperText="This won't be displayed to user"
/>
</VStack>
<VStack>
<Text as="p" font="headline">
Positive sentiment
</Text>
<TextInput
label="Address"
helperText="Valid BTC address"
variant="positive"
placeholder="HaeJiWplJohn6W42eCq0Qqft0"
end={<InputIcon active color="fgPositive" name="visible" />}
/>
</VStack>
<VStack>
<Text as="p" font="headline">
Negative Sentiment
</Text>
<TextInput
label="Address"
helperText="Invalid BTC address"
variant="negative"
placeholder="HaeJiWplJohn6W42eCq0Qqft0"
end={<InputIcon active color="fgNegative" name="visible" />}
/>
</VStack>
</VStack>
Color Surge Enabled
<VStack gap={3}>
<TextInput
label="Default Color Surge"
placeholder="Focus me"
helperText="This won't be displayed to user"
enableColorSurge
/>
<TextInput
label="Positive Color Surge"
placeholder="Focus me"
helperText="Valid BTC address"
variant="positive"
enableColorSurge
/>
<TextInput
label="Negative Color Surge"
placeholder="Focus me"
helperText="Invalid BTC address"
variant="negative"
enableColorSurge
/>
</VStack>
Content Alignment
<VStack gap={3}>
<VStack>
<Text as="p">
<strong>Left aligned (default): </strong>
</Text>
<TextInput label="City/town" placeholder="Oakland" />
</VStack>
<VStack>
<Text as="p">Right aligned:</Text>
<TextInput
label="Limit price"
size="s"
labelVariant="inside"
align="end"
type="number"
step="0.01"
placeholder="29.3"
suffix="USD"
/>
</VStack>
</VStack>
Label Variants
TextInput supports two label variants: outside (default) and inside. size and labelVariant are independent — use labelVariant="inside" with any size. At sizes s and m, an inside label sits inline in the start slot; at size l, it stacks vertically above the field.
WarningWhen using the inside label variant, you should always include a placeholder prop.
<VStack gap={3}>
<VStack>
<Text as="p">
<strong>Outside label (default):</strong>
</Text>
<TextInput label="Email Address" placeholder="Enter your email" />
</VStack>
<VStack>
<Text as="p">
<strong>Inside label:</strong>
</Text>
<TextInput label="Email Address" labelVariant="inside" placeholder="Enter your email" />
</VStack>
<VStack>
<Text as="p">
<strong>Inside label (with start content):</strong>
</Text>
<TextInput
label="Search"
labelVariant="inside"
start={<InputIconButton name="search" />}
placeholder="Search for anything"
/>
</VStack>
<VStack>
<Text as="p">
<strong>Inside label (with end content):</strong>
</Text>
<TextInput
label="Password"
labelVariant="inside"
type="password"
end={<InputIconButton name="visible" />}
placeholder="Enter your password"
/>
</VStack>
</VStack>
Custom Label
You can pass a ReactNode to labelNode to render a custom label. If you want to include a tooltip, ensure the touch target is at least 24x24 for accessibility compliance.
<VStack gap={2}>
<TextInput
accessibilityLabel="Display name"
id="display-name-input"
labelNode={
<HStack alignItems="center">
<InputLabel htmlFor="display-name-input">Display name</InputLabel>
{}
<Tooltip content="This will be visible to other users.">
<Icon active color="fg" name="info" padding={0.75} size="xs" tabIndex={0} />
</Tooltip>
</HStack>
}
placeholder="Satoshi Nakamoto"
/>
<TextInput
accessibilityLabel="Amount"
size="s"
labelVariant="inside"
labelNode={
<InputLabel>
<HStack alignItems="center" gap={0.5}>
Amount
<Text color="fgNegative" font="label1">
*
</Text>
</HStack>
</InputLabel>
}
placeholder="0.00"
suffix="USD"
/>
<TextInput
accessibilityLabel="Bio"
id="bio-input"
labelVariant="inside"
labelNode={
<InputLabel htmlFor="bio-input" paddingY={0}>
<HStack alignItems="center" gap={1}>
Bio
<Text color="fgMuted" font="legal">
(optional)
</Text>
</HStack>
</InputLabel>
}
placeholder="Tell us about yourself"
/>
<TextInput
accessibilityLabel="Notes"
id="notes-input"
labelVariant="inside"
labelNode={
<InputLabel htmlFor="notes-input" paddingY={0}>
Notes
</InputLabel>
}
placeholder="Add a note"
start={<InputIcon name="pencil" />}
/>
</VStack>
StartContent & EndContent
function StartContentExamples() {
return (
<VStack gap={3}>
<VStack>
<Text as="p">
<strong>Asset</strong>: Asset objects are not interactive
</Text>
<TextInput
label="Address"
start={
<Box paddingX={2}>
<Avatar
size="l"
src="https://dynamic-assets.coinbase.com/e785e0181f1a23a30d9476038d9be91e9f6c63959b538eabbc51a1abc8898940383291eede695c3b8dfaa1829a9b57f5a2d0a16b0523580346c6b8fab67af14b/asset_icons/b57ac673f06a4b0338a596817eb0a50ce16e2059f327dc117744449a47915cb2.png"
alt="address"
/>
</Box>
}
placeholder="HaeJiWplJohn6W42eCq0Qqft0"
/>
</VStack>
<VStack>
<Text as="p">
<strong>Icon</strong>: Icon objects are not interactive.
</Text>
<TextInput label="Amount" start={<InputIcon name="cashUSD" />} placeholder="1234" />
</VStack>
<VStack>
<Text as="p">
<strong>IconButton</strong>: The most common use case for Icon Button at the start of a
Text Field is search.
</Text>
<TextInput
label="Search"
start={<InputIconButton name="search" />}
placeholder="Search for anything"
/>
</VStack>
</VStack>
);
}
Read Only
TextInput supports a read-only state which is visually distinct from the disabled state. Read-only inputs have a secondary background color and can still be focused.
<VStack gap={3}>
<TextInput label="Read Only Input" readOnly value="This value cannot be edited" />
<TextInput label="Read Only with Suffix" readOnly value="1234.56" suffix="USD" />
<TextInput
label="Read Only with Start Content"
readOnly
value="BTC Address"
start={<InputIconButton name="search" />}
/>
</VStack>
Here are some examples and best practices when using end content in a TextField.
<VStack gap={3}>
<VStack>
<Text as="p">
<strong>Icon</strong>: Icon objects are not interactive.
</Text>
<TextInput
label="Address"
placeholder="1234 Abc Way"
end={<InputIcon name="checkmark" color="fgPositive" />}
/>
</VStack>
<VStack>
<Text as="p">
The most common use case for placing a text object at the end of an input is currency. This
object is not interactive.
</Text>
<TextInput
label="Amount"
type="number"
step="0.01"
size="s"
labelVariant="inside"
placeholder="98329.23"
suffix="USD"
/>
</VStack>
<VStack>
<Text as="p">
You can add a Text Button object at the end of an Input. "Copy" is a great example of this.
</Text>
<TextInput
label="API Access Token"
placeholder="HaeJiWplJohn6W42eCq0Qqft0"
end={
<Box spacingEnd={2}>
<Link variant="caption" color="primary" to="">
COPY
</Link>
</Box>
}
/>
</VStack>
</VStack>
Password Input - Use Icon Buttons at the end for actions like showing a password or clearing text from an input.
a11y tip: Always provide an accessibilityLabel to start/end nodes to clearly communicate state/actions
function PasswordInput() {
const [isVisible, setIsVisible] = useState(false);
const type = useMemo(() => (isVisible ? 'text' : 'password'), [isVisible]);
const iconName = useMemo(() => (isVisible ? 'visible' : 'invisible'), [isVisible]);
return (
<TextInput
label="Password"
type={type}
end={
<InputIconButton
name={iconName}
onClick={() => setIsVisible((isVisible) => !isVisible)}
accessibilityLabel={isVisible ? 'Hide password' : 'Show password'}
/>
}
/>
);
}
If needed, you can add a Link + Icon Button like this example here. Use this sparingly and only at the End of an Input.
function CopyTextField() {
const [copied, setCopied] = useState(false);
const [variant, setVariant] = useState('foregroundMuted');
const [helperText, setHelperText] = useState('');
useEffect(() => {
if (copied) {
setVariant('positive');
setHelperText('Your token has been copied!');
} else {
setVariant('foregroundMuted');
setHelperText('');
}
}, [copied]);
const handleOnChange = useCallback(() => {
setVariant('foregroundMuted');
setCopied(false);
setHelperText('');
}, []);
return (
<TextInput
end={
<HStack>
<Link onClick={() => setCopied(true)} variant="caption" color={variant}>
{copied ? 'copied' : 'copy'}
</Link>
<InputIcon active color="primary" name="visible" />
</HStack>
}
onChange={handleOnChange}
variant={variant}
helperText={helperText}
label="API Access Token"
/>
);
}
Disabled
<VStack gap={3}>
<TextInput label="Label" disabled />
<TextInput label="Label" size="s" labelVariant="inside" disabled />
</VStack>
We recommend that you use spacing 3 when building stacked forms.
function FormExample() {
const gap = 3;
const onSubmit = useCallback((e) => {
e.preventDefault();
console.log(e.currentTarget.nodeValue);
alert('Submitted');
}, []);
return (
<form onSubmit={onSubmit} action={undefined}>
<VStack gap={gap}>
<TextInput
label="Street address"
placeholder="4321 Jade Palace"
helperText="Please enter your primary address."
/>
<TextInput label="Unit #" aria-required="true" />
<HStack gap={gap}>
<TextInput label="City/town" width="70%" />
<TextInput label="State" width="30%" />
</HStack>
<HStack gap={gap}>
<TextInput label="Postal code" width="40%" />
<TextInput label="Country" width="60%" />
</HStack>
<ButtonGroup>
<Button type="submit">Save</Button>
</ButtonGroup>
</VStack>
</form>
);
}
<HStack gap={2} alignItems="center">
<TextInput
label="Email"
placeholder="satoshi@nakamoto.com"
helperText="Please enter a valid email address"
/>
<Box spacingTop={0.5}>
<Button variant="primary">Submit</Button>
</Box>
</HStack>
Testing
You can also use the testIDMap to test different parts
of the TextInput. If you use testID, it will add the testID to the root
of the TextInput.
function testExample() {
const testIDMap = useMemo(() => {
return {
input: 'input-id',
helperText: 'helperText-id',
label: 'label-id',
start: 'start-id',
end: 'end-id',
};
}, []);
return (
<TextInput
label="Email"
placeholder="satoshi@nakamoto.com"
helperText="Please enter a valid email address"
testIDMap={testIDMap}
start={
<Box paddingX={2}>
<Avatar
size="l"
src="https://dynamic-assets.coinbase.com/e785e0181f1a23a30d9476038d9be91e9f6c63959b538eabbc51a1abc8898940383291eede695c3b8dfaa1829a9b57f5a2d0a16b0523580346c6b8fab67af14b/asset_icons/b57ac673f06a4b0338a596817eb0a50ce16e2059f327dc117744449a47915cb2.png"
alt="address"
/>
</Box>
}
end={<InputIcon active color="primary" name="visible" />}
/>
);
}