Skip to content
SkillCodex
Menu

Search field

Search field

A text input inside a named search form that submits a query to find matching content.

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 search the catalogtype words and press Enter to find resultsa site search with a clear button

All phrasings
Save and share

Recognize

Enter text

Try it

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

Search field

Shared trial context

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

Search field

Mission

Search field

Search for dialog, submit the query, then open one of the displayed concept results.

Live result

No active search: all concepts remain available.

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 named search landmark contains the query field, visible submit action, and clear control when populated.
Edge case
A query with no match shows an explicit empty result, while the simulated failure preserves the input and offers Retry.

What this example shows

Search field submits a query; Text field edits a general value, while Textarea accepts multiline content.

Which fits your need?

Search field

Searching a site, catalog, or results collection

Text field

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

Which component will you use here?
Difference and sources

Search field submits a query; Text field edits a general value, while Textarea accepts multiline content.

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

      Search field belongs to this comparison group.

    • Do not confuse

      Text field

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

      Compare this pair
    • Do not confuse

      Textarea

      Choose Search field if the user looks for something and expects results, not storage. Choose Textarea if the user writes a message, note, or description that spans several lines.

      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: search box, query field, site search

    • a box to search the catalog
    • type words and press Enter to find results
    • a site search with a clear button
    • enter a query in the header
    • find matching articles from this field
    • a search input without suggestion options

    Choose

    Use it when

    • Searching a site, catalog, or results collection
    • Providing a clear and repeatable query submission

    Avoid it when

    • The text is a general form property
    • Selectable suggestions are required but Combobox behavior is not implemented

    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

      Search for the same phrase once with Enter and once with the visible search button.

      Expected result

      Both methods run the same query and produce the same result state.

    2. 2. Do this

      Clear the query using the provided clear control, then type a new search.

      Expected result

      The field is empty and focused, and the empty-query behavior is clear before you start again.

    3. 3. Do this

      Submit a phrase with no matches, then correct it without leaving the field.

      Expected result

      No results is stated explicitly, your query stays editable, and updated results do not unexpectedly move focus.

    Full contract
    1. 1The field lives in a named search form
    2. 2Enter and the visible submit action run the same query
    3. 3Clear keeps focus and updates results predictably
    4. 4Loading, no-result, error, and empty-query states are explicit

    Understand → Recognize → Choose → Compare

    Pack for your agent

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

    Implement correctly

    Build Search field without breaking its behavior

    # Implement Search field in your agent
    
    ## Objective
    Implement Search field for this verified behavior: A text input inside a named search form that submits a query to find matching content.
    
    ## Prerequisites
    - Inspect the repository, design system, and existing tests first.
    - Preserve unrelated changes and keep the file scope bounded.
    - Confirm that Search field matches the need before writing code.
    
    ## Required behavior
    - Enter submits the current query through a named search form without changing the field pattern.
    - The clear control empties the query, keeps focus in the field, and updates results predictably.
    - A specific inline message identifies the invalid field and explains how to correct it.
    
    ## States to cover
    - Search idle with an empty query
    - Search query ready to submit
    - Search loading
    - Search results visible
    - No search results
    - Search error
    - Search result opened
    
    ## Accessibility
    - ARIA role: search > input[type=search]
    - The primary control or named region for Search field has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    - Submitting leaves focus in the search form while results update below; clearing returns focus to the query field.
    - Not applicable: results update inline; Clear removes the query, submitted results, opened-result status, and errors.
    - The search landmark name, field label, submitted query, result count, loading, no-result, and error states are exposed.
    - Tab focuses the query field
    - Enter submits the search
    - Tab reaches the explicit clear and submit controls
    
    ## When not to use
    - The text is a general form property
    - Selectable suggestions are required but Combobox behavior is not implemented
    
    ## Acceptance criteria
    - The field lives in a named search form
    - Enter and the visible submit action run the same query
    - Clear keeps focus and updates results predictably
    - Loading, no-result, error, and empty-query states are explicit
    
    ## 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 Search field on a real journey

    # Verify Search field after implementation
    
    ## Objective
    Audit the Search 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:e5e6c3d803711814c00fd471193ca98162cec37b3089b15a434b167a614551d3

    Diagnose a problem

    Find and fix the Search field defect

    # Debug Search 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 Search 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
    - The field lives in a named search form
    - Enter and the visible submit action run the same query
    - Clear keeps focus and updates results predictably
    - Loading, no-result, error, and empty-query states are explicit
    
    ## 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 Search field fix

    # Prevent the Search field regression
    
    ## Objective
    Turn the reproduced cause into a focused regression test and compare Search 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:99fd20870f5ce96df968bd0aff346f097c53facabf701a9ccdb15e827dd7d5d1

    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:e2b34046c9b40067ef4936cfa465d194f4683aaee064270e864accddfe5c5d97

    In code

    TechnologyPrimitiveVersionCaveat
    Web platform

    form[role=search] with input[type=search]

    NativeA plain search field submits a query. Selectable filtered suggestions make the interaction a Combobox.

    Technical details

    Behaviors

    • Submit a query

      Enter submits the current query through a named search form without changing the field pattern.

    • Clear the query

      The clear control empties the query, keeps focus in the field, and updates results predictably.

    • Explain validation

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

    States

    • Search idle with an empty query

      Search idle with an empty query

    • Search query ready to submit

      Search query ready to submit

    • Search loading

      Search loading

    • Search results visible

      Search results visible

    • No search results

      No search results

    • Search error

      Search error

    • Search result opened

      Search result opened

    State transitions

    • Search idle with an empty query → Search query ready to submit

      Typing meaningful search terms reveals the clear control and prepares explicit submission.

    • Search query ready to submit → Search loading

      Enter or the visible Search action starts one request and blocks duplicate submission.

    • Search loading → Search results visible

      The request finishes with matching concepts and exposes their result buttons.

    • Search loading → No search results

      The request finishes without a match and exposes the explicit No concept found state.

    • Search loading → Search error

      The simulated error query fails while preserving the input and exposing Retry with an example.

    • Search error → Search loading

      Retry with an example replaces the query with keyboard shortcuts and starts one new request.

    • Search results visible → Search result opened

      Activating a result marks that concept as opened in the demonstration.

    • Search results visible → Search query ready to submit

      Editing the submitted query marks it ready for a new explicit search.

    • Search query ready to submit → Search idle with an empty query

      The clear control removes the query while preserving focus in the search field.

    • Search results visible → Search idle with an empty query

      The clear control removes the submitted query and results while preserving field focus.

    • No search results → Search idle with an empty query

      The clear control removes the unmatched query and preserves focus in the field.

    • Search result opened → Search loading

      Submitting after opening a result clears the opened-result status and starts the current query.

    • No search results → Search query ready to submit

      Editing an unmatched submitted query removes the empty result and prepares a new search.

    • Search error → Search query ready to submit

      Editing the failed query removes the error and prepares explicit resubmission.

    • Search loading → Search query ready to submit

      Editing during loading cancels the pending result update and prepares the changed query.

    • Search loading → Search idle with an empty query

      Clear during loading cancels the pending result update, empties the query, and preserves focus.

    • Search error → Search idle with an empty query

      Clear removes the failed query and error while preserving focus in the field.

    • Search result opened → Search idle with an empty query

      Clear removes the query, results, and opened-result status while preserving field focus.

    Test scenarios

    Context
    A concept directory searches known UI concept names after explicit submission.
    Mission
    Search for dialog, submit the query, then open one of the displayed concept results.
    Primary state
    The named search landmark contains the query field, visible submit action, and clear control when populated.
    Edge case
    A query with no match shows an explicit empty result, while the simulated failure preserves the input and offers Retry.

    Visual signals

    • Labeled or clearly named query input
    • Search submit action
    • Clear control appears when a query exists

    Behavioral signals

    • Enter submits the current query
    • Clear empties the query and keeps focus
    • Suggestions, if selectable, change the pattern to Combobox

    Accessibility

    Role
    search > input[type=search]
    Accessible name
    The primary control or named region for Search field has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    Focus
    Submitting leaves focus in the search form while results update below; clearing returns focus to the query field.
    Dismissal
    Not applicable: results update inline; Clear removes the query, submitted results, opened-result status, and errors.
    Scroll
    The focused field, helper text, and validation message remain visible while the page or an on-screen keyboard changes the viewport.
    Announcement
    The search landmark name, field label, submitted query, result count, loading, no-result, and error states are exposed.
    Keyboard
    • Tab focuses the query field
    • Enter submits the search
    • Tab reaches the explicit clear and submit controls

    Bindings

    Open the HTML, ARIA, Radix, and shadcn matrix
    • form[role=search] with input[type=search]

      implementationKind
      native
      nativeElement
      form[role=search] with input[type=search]
      ariaPattern
      search landmark and searchbox
      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: A plain search field submits a query. Selectable filtered suggestions make the interaction a Combobox.

      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: Search 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: Search field: normative native semantics, states, attributes, and browser behavior for HTML form controls.

    • 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: Search field: normative ARIA role definitions and constraints for the stated accessible role.

    • 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: Search field: informative WCAG guidance for evaluating visible keyboard focus appearance.

    • WAI-ARIA APG: Combobox Pattern
      sourceId
      source-ui-aria-combobox
      kind
      documentation
      canonicalUrl
      https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
      publisher
      W3C WAI
      sourceRevision
      http-last-modified:2026-07-09T07:07:35Z
      consultedAt
      2026-07-19
      license
      Not stated
      contentDigest
      sha256:d603b09b28e04f4aa72706d55623e781db6001f875a70b97da62f457e92f87e3
      status
      verified

      Claim covered: Search field: informative APG guidance for the combobox pattern: roles, states, relationships, and keyboard interaction.