Text field

To add the Textfield component to your app:

1
2
import { Textfield } from "@forge/react";

Description

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

Props

Examples

Basic

A basic text field. Use the Label component to describe what the user should enter in the text field.

1
2
import { Label, Textfield } from "@forge/react";

export default function TextfieldBasicExample() {
  return (
    <>
      <Label labelFor="textfield">Field label</Label>
      <Textfield name="basic" id="textfield" />
    </>
  );
}

Field label and message

Always use a label component for each field and associate the label to the field properly. Use the HelperMessage component for any optional field-related message.

Required field label

For required fields, always add RequiredAsterisk component next to the label.

Validation

Use ErrorMessage or ValidMessage components to display validation-related messages.

1
2
import React, { useState } from "react";
import { ErrorMessage, Label, RequiredAsterisk, Textfield } from "@forge/react";

export default function TextfieldValidation() {
  const [error, setError] = useState(undefined);

  const validate = (value) => {
    if (value.length === 0) {
      setError('This field is required');
    } else {
      setError(undefined);
    }
  };

  return (
    <>
      <Label labelFor="textfield">
        Field label
        <RequiredAsterisk />
      </Label>
      <Textfield
        appearance="standard"
        placeholder="Placeholder"
        onChange={validate}
      />
      {error && <ErrorMessage>{error}</ErrorMessage>}
    </>
  );
}

Appearance

Standard

The default text field appearance.

1
2
export default function TextfieldAppearanceStandard() {
  return (
    <Textfield
      appearance="standard"
      placeholder="Enter project name"
    />
  );
}

Subtle

A text field that's transparent until focused.

1
2
export default function TextfieldAppearanceSubtle() {
  return (
    <Textfield
      appearance="subtle"
      placeholder="Enter project name"
    />
  );
}

Spacing

Compact

A text field with compact spacing.

1
2
import { Label, Textfield } from "@forge/react";

export default function TextfieldCompact() {
  return (
    <>
      <Label labelFor="textfield">Field label</Label>
      <Textfield
        id="textfield"
        spacing="compact"
        defaultValue="Compact text field"
      />
    </>
  );
}

States

The different states a text field can be in.

1
2
import { Label, Textfield } from "@forge/react";

export default function TextfieldStates() {
  return (
    <Stack space="space.300">
      <Box>
        <Label labelFor="textfield">Field label</Label>
        <Textfield
          id="textfield"
          defaultValue="Disabled"
          isDisabled
        />
      </Box>
      <Box>
        <Label labelFor="textfield">Field label</Label>
        <Textfield
          id="textfield"
          defaultValue="Invalid"
          isInvalid
        />
      </Box>
      <Box>
        <Label labelFor="textfield">Field label</Label>
        <Textfield
          id="textfield"
          defaultValue="Read-only"
          isReadOnly
        />
      </Box>
      <Box>
        <Label labelFor="textfield" isRequired>Field label</Label>
        <Textfield
          id="textfield"
          defaultValue="Invalid"
          isRequired
        />
      </Box>
    </Stack>
  );
}

Elements before and after

Standard

Elements can be added before and after the input.

1
2
import { Textfield, Icon } from "@forge/react";

export default function TextfieldElements() {
  return (
    <Stack space="space.300">
      <Textfield
        elemBeforeInput={
          <Box xcss={{ marginTop: "space.050", marginLeft: "space.100" }}>
            <Icon glyph="user-avatar-circle" label="User" />
          </Box>
        }
        placeholder="Before input"
      />
      <Textfield
        elemAfterInput={
          <Box xcss={{ marginTop: "space.050", marginRight: "space.100" }}>
            <Icon glyph="error" label="error" />
          </Box>
        }
        placeholder="After input"
      />
    </Stack>
  );
}

Text field in a form component

Validation can be applied to a text field when used in a Form component along with the useForm hook.

1
2
import { Form, Field, Label, Textfield, Button, ErrorMessage, useForm } from "@forge/react";

export default function TextfieldFormExample() {

  const { handleSubmit, register, getFieldId, formState } = useForm();

  return (
    <Form onSubmit={handleSubmit((data) => console.log(data))}>
      <Button onClick={() => console.log(formState)}>Log form state</Button>
      <FormHeader title="Form header" />
      <FormSection>
        <Label labelFor={getFieldId("textfield")}>Field label</Label>
        <Textfield {...register("textfield", { minLength: 10 })} />
        {formState.errors.textfield && (
          <ErrorMessage>Minimum 10 characters required</ErrorMessage>
        )}
      </FormSection>
      <FormFooter align="start">
        <Button appearance="primary" type="submit">
          Submit
        </Button>
      </FormFooter>
    </Form>
  );
}

Accessibility considerations

When using the Textfield component, we recommend keeping the following accessibility considerations in mind:

• Make sure all fields have a visible label. If you're not using the provided field Label component, make sure the label is associated properly to the field for accessibility.
• Avoid using placeholder text whenever possible. Make sure any critical information is communicated either in the field label or using helper text below the field. Search fields or brief examples are the only exceptions where placeholder text is okay.