# TextInput
**📖 Live documentation:** https://cds.coinbase.com/components/inputs/TextInput/
A control for entering text.
## Import
```tsx
import { TextInput } from '@coinbase/cds-web/controls/TextInput'
```
## Examples
**Note** TextField extends props from [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes) on web. On mobile, it extends [TextInputProps](https://reactnative.dev/docs/textinput#props) from react-native.
#### Input Label
Default composition of Inputs.
```jsx live
COPY
}
/>
Use the compact variant when space is tight.
```
#### 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".
```jsx
```
Example of passing an accessibilityLabel. For web, this will set aria-label="Enter a Coinbase Email" under the hood
```jsx
```
:::tip Accessibility tip
Like 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 `TextInput`s 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.
##### Message format
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:
:::
```jsx live
```
#### Placeholder Text
```jsx live
```
#### 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.
```jsx live
```
#### Helper Text
##### Default Sentiment
```jsx live
Default sentiment
Positive sentiment
}
/>
Negative Sentiment
}
/>
```
#### Color Surge Enabled
```jsx live
```
#### Content Alignment
```jsx live
Left aligned (default): Right aligned (with compact):
```
#### Label Variants
TextInput supports two label variants: `outside` (default) and `inside`. Note that the `compact` prop, when set to true, will override label variant preference.
:::warning
When using the `inside` label variant, you should always include a `placeholder` prop.
:::
```jsx live
Outside label (default):Inside label:Inside label (with start content):}
placeholder="Search for anything"
/>
Inside label (with end content):}
placeholder="Enter your password"
/>
```
#### 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.
```jsx live
Display name
{/* Add padding to ensure 24x24 tooltip tap target for a11y compliance */}
}
placeholder="Satoshi Nakamoto"
/>
Amount
*
}
placeholder="0.00"
suffix="USD"
/>
Bio
(optional)
}
placeholder="Tell us about yourself"
/>
Notes
}
placeholder="Add a note"
start={}
/>
```
#### StartContent & EndContent
##### Examples of Input Objects placed at the Start
```jsx live
function StartContentExamples() {
return (
Asset: Asset objects are not interactive
}
placeholder="HaeJiWplJohn6W42eCq0Qqft0"
/>
Icon: Icon objects are not interactive.
} placeholder="1234" />
IconButton: The most common use case for Icon Button at the start of a
Text Field is search.
}
placeholder="Search for anything"
/>
);
}
```
#### 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.
```jsx live
}
/>
```
### Example of Input Objects placed at the End
Here are some examples and best practices when using end content in a TextField.
```jsx live
Icon: Icon objects are not interactive.
}
/>
The most common use case for placing a text object at the end of an input is currency. This
object is not interactive.
You can add a Text Button object at the end of an Input. "Copy" is a great example of this.
COPY
}
/>
```
#### Password input
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
```jsx live
function PasswordInput() {
const [isVisible, setIsVisible] = useState(false);
const type = useMemo(() => (isVisible ? 'text' : 'password'), [isVisible]);
const iconName = useMemo(() => (isVisible ? 'visible' : 'invisible'), [isVisible]);
return (
setIsVisible((isVisible) => !isVisible)}
accessibilityLabel={isVisible ? 'Hide password' : 'Show password'}
/>
}
/>
);
}
```
#### Link + Icon Button
If needed, you can add a Link + Icon Button like this example here. Use this sparingly and only at the End of an Input.
```jsx live
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 (
setCopied(true)} variant="caption" color={variant}>
{copied ? 'copied' : 'copy'}
}
onChange={handleOnChange}
variant={variant}
helperText={helperText}
label="API Access Token"
/>
);
}
```
#### Disabled
```jsx live
```
#### Example of a Form
We recommend that you use spacing 3 when building stacked forms.
```jsx live
function FormExample() {
const gap = 3;
const onSubmit = useCallback((e) => {
e.preventDefault();
console.log(e.currentTarget.nodeValue);
alert('Submitted');
}, []);
return (
);
}
```
#### Example of a Sign Up Form
```jsx live
```
### Testing
#### Testing different parts of the input
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.
```jsx live
function testExample() {
const testIDMap = useMemo(() => {
return {
input: 'input-id',
helperText: 'helperText-id',
label: 'label-id',
start: 'start-id',
end: 'end-id',
};
}, []);
return (
}
end={}
/>
);
}
```
## Props
| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `align` | `center \| start \| end \| justify` | No | `start` | Text Align Input |
| `alignContent` | `ResponsiveProp