Text field

A text field is an input that allows a user to write or edit text.

Basic

A basic text field. If you use a text field outside of a form component, always use a label and associate the label to the field properly.

Field label

import React from 'react';

import { Label } from '@atlaskit/form/label/default';
import Textfield from '@atlaskit/textfield/text-field';

export default function TextFieldBasicExample(): React.JSX.Element {
	return (
		<>
			<Label htmlFor="basic-textfield">Field label</Label>
			<Textfield name="basic" id="basic-textfield" />
		</>
	);
}

Text field in a form component

You'll often use text fields as a form field, which must include a visible label.

import React from 'react';

import Button from '@atlaskit/button/default/button';
import Form from '@atlaskit/form/form';
import Field from '@atlaskit/form/field';
import { FormFooter } from '@atlaskit/form/form-footer';
import Textfield from '@atlaskit/textfield/text-field';

export default function TextFieldFormExample(): React.JSX.Element {
	return (
		<Form onSubmit={(formState: unknown) => console.log('form submitted', formState)}>
			<Field
				label="Field label"
				name="example-text"
				helperMessage="Help or instruction text goes here"
				component={({ fieldProps }: any) => <Textfield {...fieldProps} />}
			/>
			<FormFooter>
				<Button type="submit" appearance="primary">
					Submit
				</Button>
			</FormFooter>
		</Form>
	);
}

Validation

Native

Validation can display a native error message related to the restrictions of the pattern attribute. Keep this text as short as possible. Use the writing guidelines for more help. For complicated information, provide a link to more information in a new browser tab.

import React, { Fragment } from 'react';

import Button from '@atlaskit/button/default/button';
import Form from '@atlaskit/form/form';
import Field from '@atlaskit/form/field';
import { FormFooter } from '@atlaskit/form/form-footer';
import Textfield from '@atlaskit/textfield/text-field';

export default function TextFieldFormNativeValidationExample(): React.JSX.Element {
	return (
		<Form
			onSubmit={(formData) => console.log('form data', formData)}
			name="native-validation-example"
		>
			<Field
				label="Input must contain less than 20 characters"
				name="command"
				isRequired
				defaultValue=""
			>
				{({ fieldProps }: any) => (
					<Fragment>
						<Textfield {...fieldProps} pattern=".{0,20}" data-testid="nativeFormValidationTest" />
					</Fragment>
				)}
			</Field>
			<Field label="Input must be numeric" name="number" isRequired defaultValue="">
				{({ fieldProps }: any) => (
					<Fragment>
						<Textfield {...fieldProps} type="number" data-testid="nativeFormValidationTestNumber" />
					</Fragment>
				)}
			</Field>
			<Field label="Input must be an email" name="email" isRequired defaultValue="">
				{({ fieldProps }: any) => (
					<Fragment>
						<Textfield
							{...fieldProps}
							type="email"
							data-testid="nativeFormValidationTestEmail"
							autoComplete="email"
						/>
					</Fragment>
				)}
			</Field>
			<Field label="Password must not be empty" name="password" isRequired defaultValue="">
				{({ fieldProps }: any) => (
					<Fragment>
						<Textfield
							{...fieldProps}
							type="password"
							data-testid="nativeFormValidationTestPassword"
						/>
					</Fragment>
				)}
			</Field>
			<FormFooter>
				<Button type="submit" appearance="primary">
					Submit
				</Button>
			</FormFooter>
		</Form>
	);
}

Custom

import React, { Fragment, useState } from 'react';

import Button from '@atlaskit/button/default/button';
import Form from '@atlaskit/form/form';
import { ErrorMessage } from '@atlaskit/form/error-message';
import Field from '@atlaskit/form/field';
import { FormFooter } from '@atlaskit/form/form-footer';
import { MessageWrapper } from '@atlaskit/form/message-wrapper';
import { ValidMessage } from '@atlaskit/form/valid-message';
import Textfield from '@atlaskit/textfield/text-field';

export default function FormValidationExample(): React.JSX.Element {
	const [fieldValue, setFieldValue] = useState<string | undefined>('');
	const [fieldHasError, setFieldHasError] = useState(false);

	function validate(value: string | undefined) {
		setFieldValue(value);
		if (value === 'regular user') {
			setFieldHasError(false);
		} else {
			return 'INCORRECT_PHRASE';
		}
		return undefined;
	}

	const handleSubmit = (formState: { command: string }) => {
		console.log('form state', formState);
	};

	const handleBlurEvent = () => {
		if (fieldValue !== 'regular user') {
			setFieldHasError(true);
		}
	};

	return (
		<Form onSubmit={handleSubmit} name="validation-example">
			<Field
				label="Validates entering existing role"
				isRequired
				name="command"
				validate={validate}
				defaultValue=""
			>
				{({ fieldProps: { onBlur: fieldOnBlur, ...fieldProps }, meta: { valid } }: any) => (
					<Fragment>
						<Textfield
							{...fieldProps}
							testId="formValidationTest"
							onBlur={() => {
								// When defining your own onBlur handler, additionally call onBlur from the fieldProps to propagate internal field state
								handleBlurEvent();
								fieldOnBlur();
							}}
						/>
						<MessageWrapper>
							{valid && <ValidMessage>Your role is valid</ValidMessage>}
							{fieldHasError && (
								<ErrorMessage>Incorrect, try &lsquo;regular user&rsquo;</ErrorMessage>
							)}
						</MessageWrapper>
					</Fragment>
				)}
			</Field>
			<FormFooter>
				<Button type="submit" appearance="primary">
					Submit
				</Button>
			</FormFooter>
		</Form>
	);
}

Appearance

Standard

The default text field appearance.

import React from 'react';

import Textfield from '@atlaskit/textfield/text-field';

export default function TextFieldAppearanceStandard(): React.JSX.Element {
	return <Textfield appearance="standard" label="Standard" placeholder="" />;
}

Subtle

A text field that's transparent until interaction or error.

import React from 'react';

import Textfield from '@atlaskit/textfield/text-field';

export default function TextFieldAppearanceSubtle(): React.JSX.Element {
	return <Textfield appearance="subtle" label="Subtle" placeholder="" />;
}

Character counter

A character counter field provides real-time feedback about text length as people type, showing how many characters are remaining or have been exceeded.

Use it when there are constraints on text length, such as database limits, technical requirements, or design constraints.

View details and examples of character counters, (opens new window).

Elements before and after input

Text fields can include non-interactive elements before and after the input. This is useful for adding elements like icons into the text field.

Don’t nest interactive elements in the text field, as it will cause accessibility and focus issues.

import { Fragment } from 'react';

import Avatar from '@atlaskit/avatar/avatar';
import { cssMap, jsx } from '@atlaskit/css';
import Form from '@atlaskit/form/form';
import Field from '@atlaskit/form/field';
import ErrorIcon from '@atlaskit/icon/core/status-error';
import { Box } from '@atlaskit/primitives/compiled';
import Textfield from '@atlaskit/textfield/text-field';
import { token } from '@atlaskit/tokens';

const elemStyles = cssMap({
	before: {
		paddingInlineStart: token('space.075'),
	},
	after: {
		paddingInlineEnd: token('space.075'),
	},
});

export default function TextFieldElementsBeforeAndAfterExample(): JSX.Element {
	return (
		<Form
			onSubmit={(formData) => console.log('form data', formData)}
			name="elements-before-and-after-example"
		>
			<Field label="After input" name="after-input" defaultValue="">
				{({ fieldProps }: any) => (
					<Fragment>
						<Textfield
							{...fieldProps}
							elemAfterInput={
								<Box xcss={elemStyles.after}>
									<ErrorIcon label="error" />
								</Box>
							}
						/>
					</Fragment>
				)}
			</Field>
			<Field label="Before input" name="before-input" defaultValue="">
				{({ fieldProps }: any) => (
					<Fragment>
						<Textfield
							{...fieldProps}
							elemBeforeInput={
								<Box xcss={elemStyles.before}>
									<Avatar size="small" borderColor="transparent" />
								</Box>
							}
						/>
					</Fragment>
				)}
			</Field>
		</Form>
	);
}

Customization

Use the data attributes data-ds--text-field--container and data-ds--text-field--input to customize the style of the text field container and input element.

import { css, jsx } from '@compiled/react';

import Textfield from '@atlaskit/textfield/text-field';
import { token } from '@atlaskit/tokens';

const bigFontStyles = css({
	// container style
	paddingBlockEnd: token('space.075'),
	paddingBlockStart: token('space.075'),
	paddingInlineEnd: token('space.075'),
	paddingInlineStart: token('space.075'),
	'& > [data-ds--text-field--input]': {
		// input style
		fontSize: 20,
	},
});

export default function TextFieldCustomizationExample(): JSX.Element {
	return (
		<Textfield
			aria-label="customized text field"
			css={bigFontStyles}
		/>
	);
}

Was this page helpful?

We use this feedback to improve our documentation.