Skip to content
SkillCodex
Menu

Text field

Text field

A labeled single-line control for entering or editing one textual value.

Try the component
Context, sources and actions
Sources and revision
Updated
Version
v1.0.26 · r2
Sources
5 sources
Status
Published
Read the sources

You may have searched for: a box to enter my display nameone line for an email addresslet me type a short value

All phrasings
Save and share

Recognize

Enter text

Try it

Is the expected value short, multiline, or a search query?

Text field

Shared trial context

A form collects text, with field length and submission intent determining the appropriate input control.

Text field

Mission

Text field

Enter a valid name, submit, then exceed the limit and recover from the linked validation message.

Between 2 and 40 characters, on one line.

0 of 40 characters

Live result

The display name has not been saved yet.

Step 1 of 3

Try

Try the component. Your live result appears just above. Move on at your own pace.

Behavior and edge case
What to observe
The visible label, current value, and helper text remain available before any error.
Edge case
After invalid submission, the entered text remains, the precise error is linked, and focus moves only according to the form recovery plan.

What this example shows

Text field accepts one line; Textarea accepts multiple lines, while Search field submits a query through a search context.

Which fits your need?

Text field

Entering a name, email, code, or other short value

Textarea

Collecting a message, note, or description

Which component will you use here?
Difference and sources

Text field accepts one line; Textarea accepts multiple lines, while Search field submits a query through a search context.

Read the sources

    Parts of the specimen

    Select a numbered marker on the schematic, or use the list below, to see its role. The schematic shows the concept's representative state.

    Label

    The persistent text that names a control or field.

    Position in the atlas

    Relationship map

    Locate the chapter, neighboring concepts, and the next useful decision.

    • Chapter

      Enter text

      Text field belongs to this comparison group.

    • Do not confuse

      Textarea

      Choose Text field if the value is a name, email, code, or another short entry. Choose Textarea if the user writes a message, note, or description.

      Compare this pair
    • Do not confuse

      Search field

      Choose Text field if the value is a name, email, code, or another short entry kept as data. Choose Search field if the entered text is a query against a site, catalog, or result set.

      Compare this pair
    • Next step

      Compare the concepts in the chapter before choosing an implementation.

      Open the chapter

    In your own words

    Understand

    What people describe

    Documented aliases: text input, input field, single-line input

    • a box to enter my display name
    • one line for an email address
    • let me type a short value
    • a labeled form input
    • edit this account name
    • a field with help and an error below

    Choose

    Use it when

    • Entering a name, email, code, or other short value
    • Editing one textual property in a form

    Avoid it when

    • The response needs line breaks
    • The primary intent is to submit a search query

    Compare

    Compare similar concepts

    Verification checklist

    Try these actions in the lab, then check the same behaviours in your agent’s result. Adapt the example names to your interface.

    1. 1. Do this

      Enter a valid value, then select, replace and undo part of the text using normal keyboard shortcuts.

      Expected result

      Native text editing works, and a visible label keeps identifying the field after the placeholder disappears.

    2. 2. Do this

      Submit an invalid or overly long value, then correct it.

      Expected result

      Your input is preserved, the error explains the relevant constraint, and correction lets you proceed.

    3. 3. Do this

      Use Tab to reach the field and press Enter after entering a valid value.

      Expected result

      Focus is visible, and Enter follows the form’s stated submission behavior without an unrelated action.

    Full contract
    1. 1A visible label remains outside the placeholder
    2. 2Input purpose and autocomplete are correct
    3. 3Help and error text are programmatically associated
    4. 4Invalid submission preserves the user's value

    Understand → Recognize → Choose → Compare

    Pack for your agent

    Pre-written instructions to paste into your agent. Copying executes nothing.

    Implement correctly

    Build Text field without breaking its behavior

    # Implement Text field in your agent
    
    ## Objective
    Implement Text field for this verified behavior: A labeled single-line control for entering or editing one textual value.
    
    ## Prerequisites
    - Inspect the repository, design system, and existing tests first.
    - Preserve unrelated changes and keep the file scope bounded.
    - Confirm that Text field matches the need before writing code.
    
    ## Required behavior
    - Typing edits a single value while selection, clipboard, and undo behaviors remain native.
    - A specific inline message identifies the invalid field and explains how to correct it.
    
    ## States to cover
    - Display name valid
    - Display name invalid
    
    ## Accessibility
    - ARIA role: input[type=text]
    - The primary control or named region for Text field has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    - A visible focus indicator surrounds the field without hiding its value, label, or error.
    - Not applicable: the entered value remains until edited, reset, or intentionally submitted.
    - Label, input purpose, required state, helper relationship, invalid state, and specific error are exposed.
    - Tab focuses the field
    - Standard editing, selection, undo, and clipboard shortcuts remain native
    - Enter follows the surrounding form contract
    
    ## When not to use
    - The response needs line breaks
    - The primary intent is to submit a search query
    
    ## Acceptance criteria
    - A visible label remains outside the placeholder
    - Input purpose and autocomplete are correct
    - Help and error text are programmatically associated
    - Invalid submission preserves the user's value
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    
    • Web platform
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The need is tied to canonical behavior before any technical choice.
    • States, accessibility, and non-goals prevent a merely visual implementation.
    • Acceptance criteria and the output format make verification observable.

    Try next

    Verify Text field on a real journey

    # Verify Text field after implementation
    
    ## Objective
    Audit the Text field implementation against its behavior, states, and accessibility requirements without changing it automatically.
    
    ## Checks
    - Replay the smallest representative journey.
    - Check keyboard behavior, focus, accessible name, and announcements.
    - Tie each gap to a specific acceptance criterion.
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    

    sha256:2c0b00f0b3ebc6ae8d5055d516a154c9f2e6d8decac7f928b747c9ea5a67e282

    Diagnose a problem

    Find and fix the Text field defect

    # Debug Text field in your agent
    
    ## Observed symptom
    [DESCRIBE THE SYMPTOM HERE]
    
    ## Observable checks
    - Reproduce the issue with the smallest relevant journey.
    - Compare behavior with the documented states and transitions for Text field.
    - Verify keyboard behavior, focus, accessible name, and announcements.
    
    ## Possible causes
    - The chosen primitive does not match the expected behavior.
    - A state, transition, or focus return is missing.
    - A neighboring component captures an event or hides an accessible signal.
    
    ## Bounded corrections
    - Fix the reproduced cause without recreating neighboring components.
    - Preserve the public contract and add a focused regression test.
    - Do not install dependencies or change remote state without authorization.
    
    ## Final verification
    - A visible label remains outside the placeholder
    - Input purpose and autocomplete are correct
    - Help and error text are programmatically associated
    - Invalid submission preserves the user's value
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    
    • Web platform
    • Requires · Access to the repository, design system, and tests
    Why it works
    • The explicit symptom prevents starting from an assumed fix.
    • Checks separate behavior, accessibility, and neighboring interference.
    • The fix stays bounded and must produce regression evidence.

    Try next

    Lock in the Text field fix

    # Prevent the Text field regression
    
    ## Objective
    Turn the reproduced cause into a focused regression test and compare Text field with neighboring concepts before widening the fix.
    
    ## Checks
    - Prove that the test fails before the fix.
    - Prove that it passes after the bounded fix.
    - Verify that no neighboring component changed behavior.
    
    ## Guardrails
    - Show the proposed changes before any external action.
    - Do not publish, send, delete, pay for, or change remote state without explicit authorization.
    - Preserve unrelated changes and stop if the scope becomes ambiguous.
    
    ## Output format
    - Outcome or verdict.
    - Files or actions involved.
    - Checks run and observable evidence.
    - Remaining blockers or limitations.
    

    sha256:2419cf9a7ac6c7cf2b1cad64a1bd5d52ea0249a90dda03381e717fa6d83a333f

    Full entry, saving and provenance

    Pre-written instruction by SkillCodex — your request is neither sent nor used to adapt this text; no content is generated, and copying executes nothing.

    Pack digest: sha256:dbaf389a1b35eda1cf21624e909639452ed8b45448ef66b27a9130b430d44f43

    In code

    TechnologyPrimitiveVersionCaveat
    Web platform

    label with input

    NativeThe visible label stays separate from the placeholder, and help or error messages are programmatically associated.

    Technical details

    Behaviors

    • Enter text

      Typing edits a single value while selection, clipboard, and undo behaviors remain native.

    • Explain validation

      A specific inline message identifies the invalid field and explains how to correct it.

    States

    • Display name valid

      Display name valid

    • Display name invalid

      Display name invalid

    State transitions

    • Display name valid → Display name invalid

      Submitting a value above the stated length limit preserves the text and links the precise error.

    • Display name invalid → Display name valid

      Editing the value back within the stated limit resolves the linked validation error.

    Test scenarios

    Context
    A profile form edits a public display name with length guidance.
    Mission
    Enter a valid name, submit, then exceed the limit and recover from the linked validation message.
    Primary state
    The visible label, current value, and helper text remain available before any error.
    Edge case
    After invalid submission, the entered text remains, the precise error is linked, and focus moves only according to the form recovery plan.

    Visual signals

    • Persistent label above or beside the control
    • Single-line editable value
    • Helper or error text linked below

    Behavioral signals

    • Enter does not insert a line break
    • Native selection, clipboard, and undo work
    • Validation preserves the entered value

    Accessibility

    Role
    input[type=text]
    Accessible name
    The primary control or named region for Text field has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    Focus
    A visible focus indicator surrounds the field without hiding its value, label, or error.
    Dismissal
    Not applicable: the entered value remains until edited, reset, or intentionally submitted.
    Scroll
    The focused field, helper text, and validation message remain visible while the page or an on-screen keyboard changes the viewport.
    Announcement
    Label, input purpose, required state, helper relationship, invalid state, and specific error are exposed.
    Keyboard
    • Tab focuses the field
    • Standard editing, selection, undo, and clipboard shortcuts remain native
    • Enter follows the surrounding form contract

    Bindings

    Open the HTML, ARIA, Radix, and shadcn matrix
    • label with input

      implementationKind
      native
      nativeElement
      label with input
      ariaPattern
      textbox
      radixPrimitive
      Not applicable
      shadcnRecipe
      Not applicable
      runtimeDependency
      Not applicable
      packageName
      Not applicable
      exportName
      Not applicable
      exactVersion
      Not applicable
      status
      verified
      sourceId
      source-ui-html-input
      deprecationStatus
      active
      replacement
      Not applicable
      validFrom
      Not applicable
      validUntil
      Not applicable

      Equivalence caveat: The visible label stays separate from the placeholder, and help or error messages are programmatically associated.

      Verify binding source

    Sources

    • WHATWG HTML: The input element
      sourceId
      source-ui-html-input
      kind
      standard
      canonicalUrl
      https://html.spec.whatwg.org/multipage/input.html#the-input-element
      publisher
      WHATWG
      sourceRevision
      http-last-modified:2026-07-19T13:52:46Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:4699d26dbf428296b4b352b480b75c846a9a6b23cf3f124d6d6fe6b5e19d4eba
      status
      verified

      Claim covered: Text field: normative native semantics, states, attributes, and browser behavior for input.

    • WHATWG HTML: Forms
      sourceId
      source-ui-html-forms
      kind
      standard
      canonicalUrl
      https://html.spec.whatwg.org/multipage/forms.html
      publisher
      WHATWG
      sourceRevision
      http-last-modified:2026-07-19T13:52:46Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:730c20c8a823ab6b9a40c77d4731d6aab46895cd98c388fe12c966096d5bdd18
      status
      verified

      Claim covered: Text field: normative native semantics, states, attributes, and browser behavior for HTML form controls.

    • WCAG 2.2: Focus Appearance
      sourceId
      source-ui-wcag-understanding-focus-appearance
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-02T10:07:49Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:fdcf316a1f0e3cc758eda9618322d132862124ff0a3f3b1a3acbf20daf804ff0
      status
      verified

      Claim covered: Text field: informative WCAG guidance for evaluating visible keyboard focus appearance.

    • WAI-ARIA 1.2: Roles Model
      sourceId
      source-ui-wai-aria-roles
      kind
      standard
      canonicalUrl
      https://www.w3.org/TR/wai-aria-1.2/#roles
      publisher
      W3C WAI
      sourceRevision
      W3C-REC-wai-aria-1.2-20230606
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:c0fea16fc747779569ab754d2d25bca3e2b7e8a673b8ef5362aeb9ebc73a4849
      status
      verified

      Claim covered: Text field: normative ARIA role definitions and constraints for the stated accessible role.

    • WHATWG HTML: The textarea element
      sourceId
      source-ui-html-textarea
      kind
      standard
      canonicalUrl
      https://html.spec.whatwg.org/multipage/form-elements.html#the-textarea-element
      publisher
      WHATWG
      sourceRevision
      http-last-modified:2026-07-19T13:52:46Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:418a8f9ce1e8690c6d458121120b0b3b7cd907aa92b2101b85f82f7e02d5ac2f
      status
      verified

      Claim covered: Text field: normative native semantics, states, attributes, and browser behavior for textarea.