> ## Documentation Index
> Fetch the complete documentation index at: https://content-designer-ux-writing-skill-26.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Writing form fields

> Create clear form labels, instructions, and helper text that guide users through input

Form fields are where users provide information. Clear labels, helpful instructions, and well-placed helper text make forms easier to complete.

## Form field elements

Each form field can include:

<CardGroup cols={2}>
  <Card title="Label" icon="tag">
    **Required**. Describes what to enter.

    "Email address"
  </Card>

  <Card title="Instruction">
    **Optional**. Additional context about the field.

    "We'll send order updates here"
  </Card>

  <Card title="Placeholder">
    **Use sparingly**. Example format.

    "[name@example.com](mailto:name@example.com)"
  </Card>

  <Card title="Helper text">
    **Optional**. Ongoing guidance or validation.

    "Must include @ symbol"
  </Card>
</CardGroup>

## Labels

Labels are the most critical element. Every field needs a clear, visible label.

### Format

Use clear noun phrases that describe the input:

<Tabs>
  <Tab title="Good labels">
    * Email address
    * Phone number
    * Company name
    * Street address
    * Date of birth
    * Password
  </Tab>

  <Tab title="Avoid">
    * Email (too vague - could be action or field)
    * Enter your email address (instruction, not label)
    * Email: (unnecessary colon)
    * E-mail (dated spelling)
  </Tab>
</Tabs>

### Label best practices

<Steps>
  <Step title="Keep labels visible">
    Don't hide labels inside placeholder text. Placeholders disappear when users start typing.

    <Warning>
      Floating labels (labels that become placeholders) can confuse users and fail accessibility standards.
    </Warning>
  </Step>

  <Step title="Use sentence case">
    Only capitalize the first word.

    * **Good**: "Email address"
    * **Avoid**: "Email Address"
  </Step>

  <Step title="Be specific">
    Generic labels create ambiguity.

    * **Good**: "Work phone number"
    * **Avoid**: "Number"
  </Step>

  <Step title="Avoid questions">
    Labels should be noun phrases, not questions.

    * **Good**: "Company name"
    * **Avoid**: "What's your company name?"
  </Step>
</Steps>

## Instructions

Instructions provide context about why you need information or how to format it.

### When to use instructions

Add instructions when:

* The purpose isn't obvious ("We'll use this to verify your identity")
* Format is specific ("Use international format: +1-555-555-5555")
* There are constraints ("Must be a PDF under 5MB")

### Format

Start with a verb and explain why or how:

<Accordion title="Example: Email address">
  **Label**: Email address

  **Instruction**: "We'll send order confirmations here"

  **Why it works**: Explains the purpose so users know which email to use (personal vs work).
</Accordion>

<Accordion title="Example: Phone number">
  **Label**: Phone number

  **Instruction**: "Include country code for international numbers"

  **Why it works**: Explains format requirements without being demanding.
</Accordion>

<Accordion title="Example: Password">
  **Label**: Password

  **Instruction**: "Use at least 8 characters with letters and numbers"

  **Why it works**: Sets expectations upfront instead of showing error after submission.
</Accordion>

## Placeholders

<Warning>
  Use placeholders sparingly. They disappear when users type and can't replace labels.
</Warning>

### When to use placeholders

Only use placeholders to show:

* Standard format examples ("[name@example.com](mailto:name@example.com)")
* Expected data type ("MM/DD/YYYY")

### Placeholder guidelines

<Check>Never use placeholders as labels</Check>
<Check>Keep examples realistic (not "[john@email.com](mailto:john@email.com)")</Check>
<Check>Use placeholder text that's clearly not real data</Check>
<Check>Ensure sufficient color contrast (WCAG AA: 4.5:1)</Check>

### Examples

| Field         | Placeholder                                 | Why it works                                |
| ------------- | ------------------------------------------- | ------------------------------------------- |
| Email address | [name@example.com](mailto:name@example.com) | Shows format without seeming like real data |
| Phone         | (555) 555-5555                              | Demonstrates format clearly                 |
| Search        | Search projects...                          | Clarifies scope of search                   |
| URL           | [https://example.com](https://example.com)  | Shows required protocol                     |

## Helper text

Helper text provides ongoing guidance, validation feedback, or additional context.

### Types of helper text

<Tabs>
  <Tab title="Static">
    **Always visible**, provides consistent guidance.

    **Example**: Below a password field:

    "Must be at least 8 characters"

    **When to use**: For requirements that apply to all users.
  </Tab>

  <Tab title="Dynamic">
    **Appears on interaction**, like focus or typing.

    **Example**: Password strength indicator:

    "Weak password" → "Strong password"

    **When to use**: For real-time feedback on input quality.
  </Tab>

  <Tab title="Validation">
    **Appears on blur or submit**, indicates errors.

    **Example**: After leaving email field:

    "Email must include @"

    **When to use**: For input validation errors.

    <Note>
      See the [Error messages guide](/guides/error-messages) for writing validation errors.
    </Note>
  </Tab>
</Tabs>

## Required vs optional fields

### Mark required fields

Use an asterisk (\*) or "required" label:

```
Email address *
```

Or:

```
Email address (required)
```

<Tip>
  If most fields are required, mark the few optional ones instead: "Phone number (optional)"
</Tip>

### Explain requirements upfront

At the start of forms, explain what's required:

"\* Required fields"

Or:

"Only fields marked 'optional' can be skipped."

## Common patterns

### Email

```
Label: Email address
Instruction: We'll send order confirmations here
Placeholder: name@example.com
```

### Password (create)

```
Label: Create password
Instruction: Use at least 8 characters with letters and numbers
Helper: Password strength: Strong
```

### Phone

```
Label: Phone number
Instruction: Include area code
Placeholder: (555) 555-5555
```

### Credit card

```
Label: Card number
Helper: We encrypt all payment information
Placeholder: 1234 5678 9012 3456
```

### Date of birth

```
Label: Date of birth
Instruction: You must be 18 or older to create an account
Placeholder: MM/DD/YYYY
```

## Before and after examples

### Example 1: Email field

<Accordion title="❌ Before">
  **Placeholder only**: "Enter your email address"

  **Problems**:

  * No visible label
  * Placeholder disappears when typing
  * Fails accessibility requirements
</Accordion>

<Accordion title="✅ After">
  **Label**: Email address

  **Instruction**: We'll send order updates here

  **Placeholder**: [name@example.com](mailto:name@example.com)

  **Why it works**:

  * Clear, visible label
  * Explains purpose
  * Shows format example
</Accordion>

### Example 2: Password requirements

<Accordion title="❌ Before">
  **Label**: Password

  **Error after submit**: "Password must contain at least 8 characters including uppercase letters, lowercase letters, numbers and special characters."

  **Problems**:

  * Requirements hidden until error
  * Error message too long (17 words)
  * User has to remember or re-read
</Accordion>

<Accordion title="✅ After">
  **Label**: Create password

  **Instruction**: Use at least 8 characters with letters and numbers

  **Dynamic helper**: Password strength: Weak → Strong

  **Why it works**:

  * Requirements visible upfront
  * Real-time feedback
  * Clear, scannable format
</Accordion>

## Accessibility

<Check>Every field has a visible label (not just placeholder)</Check>
<Check>Labels are programmatically associated with inputs</Check>
<Check>Required fields are clearly marked</Check>
<Check>Error messages are associated with their fields</Check>
<Check>Instructions appear before the field, not after</Check>
<Check>Placeholder text has sufficient contrast (4.5:1)</Check>

## Quick checklist

For every form field:

* [ ] Has a clear, visible label (noun phrase)
* [ ] Uses sentence case
* [ ] Marks required fields with \* or (required)
* [ ] Includes instructions if purpose isn't obvious
* [ ] Uses placeholders only for format examples
* [ ] Shows validation errors near the field
* [ ] Works with screen readers

## Related resources

<CardGroup cols={3}>
  <Card title="Error messages" icon="triangle-exclamation" href="/guides/error-messages">
    Write clear validation errors
  </Card>

  <Card title="Accessibility" icon="universal-access" href="/guides/accessibility">
    Make forms accessible to all users
  </Card>

  <Card title="Quality standards" icon="star" href="/concepts/quality-standards">
    Apply the four quality standards
  </Card>
</CardGroup>