Skip to content
SkillCodex
Menu

Button

Button

A named control that performs an action in the current interface when activated.

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: click to save these changesa control that runs an actionsubmit this form

All phrasings
Save and share

Recognize

Trigger or navigate

Try it

Does the control trigger an action, change location, or need to remain icon-only?

Button

Shared trial context

A project screen lets the user trigger an operation or move to a destination from a control suited to the available space.

Button

Mission

Button

Activate Save with Space, verify the pending state blocks a second request, and recover from a server error.

Subject: Weekly summary

Live result

The draft is ready to save.

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 enabled submit button has a clear label, visible focus, and sufficient text contrast.
Edge case
During submission, the button preserves its width, exposes Saving, and blocks duplicate activation without removing focus.

What this example shows

Button performs an action; Link navigates to a destination, while Icon button is the compact button variant whose visible label is replaced by an icon.

Which fits your need?

Button

Submitting or resetting a form

Link

Moving to another page or route

Which component will you use here?
Difference and sources

Button performs an action; Link navigates to a destination, while Icon button is the compact button variant whose visible label is replaced by an icon.

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.

    Control

    The interactive element that receives input and exposes state.

    Position in the atlas

    Relationship map

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

    • Chapter

      Trigger or navigate

      Button belongs to this comparison group.

    • Do not confuse

      Link

      Choose Button if activation changes something here, such as submit, open, or delete. Choose Link if activation takes the user to another page or route that can open in a new tab.

      Compare this pair
    • Do not confuse

      Icon button

      Choose Button if the action is primary or unfamiliar and a visible label prevents misunderstanding. Choose Icon button if a familiar action repeats in a dense toolbar and space matters more than a visible label.

      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: action button, CTA button, submit button

    • click to save these changes
    • a control that runs an action
    • submit this form
    • press to create a new project
    • a main action with a clear label
    • do something without changing page location

    Choose

    Use it when

    • Submitting or resetting a form
    • Running an in-place command such as Save or Add

    Avoid it when

    • Activation primarily navigates to another URL
    • The control has no clear action name

    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

      Activate the same harmless action once with Enter and once with Space while its button is focused.

      Expected result

      Both keys trigger the intended action once, with a visible focus indicator and no unexpected navigation.

    2. 2. Do this

      Start an asynchronous action and try activating it again while it is pending.

      Expected result

      The pending state is clear, duplicate actions are prevented, and the button does not jump or lose focus unnecessarily.

    3. 3. Do this

      Use the test example’s failure case, then retry the action.

      Expected result

      Failure is distinguished from success, the action becomes usable again when appropriate, and retry reaches a clear outcome.

    Full contract
    1. 1The button performs an action rather than navigation
    2. 2Its visible label states that action
    3. 3Enter, Space, focus, disabled, and pending states work
    4. 4Text contrast and target size meet the quality bar

    Understand → Recognize → Choose → Compare

    Pack for your agent

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

    Implement correctly

    Build Button without breaking its behavior

    # Implement Button in your agent
    
    ## Objective
    Implement Button for this verified behavior: A named control that performs an action in the current interface when activated.
    
    ## Prerequisites
    - Inspect the repository, design system, and existing tests first.
    - Preserve unrelated changes and keep the file scope bounded.
    - Confirm that Button matches the need before writing code.
    
    ## Required behavior
    - Pointer, Enter, or Space activation runs one named action exactly once.
    - The content region exposes its busy state while a separate visual indicator remains redundant.
    
    ## States to cover
    - Save idle
    - Save pending
    - Save error
    - Save successful
    
    ## Accessibility
    - ARIA role: button
    - The primary control or named region for Button has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    - A high-contrast focus indicator remains visible in every enabled visual variant and pending state.
    - Not applicable: an action button does not open a surface unless that separate relationship is defined.
    - Accessible name, disabled or pressed state when applicable, and pending result are exposed without changing the label ambiguously.
    - Tab focuses the button
    - Enter and Space activate it
    - Form submit behavior follows its explicit type
    
    ## When not to use
    - Activation primarily navigates to another URL
    - The control has no clear action name
    
    ## Acceptance criteria
    - The button performs an action rather than navigation
    - Its visible label states that action
    - Enter, Space, focus, disabled, and pending states work
    - Text contrast and target size meet the quality bar
    
    ## 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 Button on a real journey

    # Verify Button after implementation
    
    ## Objective
    Audit the Button 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:e3ad88b2402fc89e324f39a708a5869e251812c4a777801dede95ecdf0634bb9

    Diagnose a problem

    Find and fix the Button defect

    # Debug Button 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 Button.
    - 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 button performs an action rather than navigation
    - Its visible label states that action
    - Enter, Space, focus, disabled, and pending states work
    - Text contrast and target size meet the quality bar
    
    ## 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 Button fix

    # Prevent the Button regression
    
    ## Objective
    Turn the reproduced cause into a focused regression test and compare Button 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:8aa43a1346558e33de34377af0d3377a092473973ba96d52a8af74b722130b33

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

    In code

    TechnologyPrimitiveVersionCaveat
    Web platform

    button[type=button|submit|reset]

    NativeA button performs an action. Navigation belongs to a link, and an explicit type prevents accidental form submission.

    Technical details

    Behaviors

    • Run an action

      Pointer, Enter, or Space activation runs one named action exactly once.

    • Mark the region busy

      The content region exposes its busy state while a separate visual indicator remains redundant.

    States

    • Save idle

      Save idle

    • Save pending

      Save pending

    • Save error

      Save error

    • Save successful

      Save successful

    State transitions

    • Save idle → Save pending

      Enter, Space, pointer, or touch activates Save exactly once.

    • Save pending → Save error

      The save request fails and exposes a retryable error without duplicating the request.

    • Save error → Save pending

      Activating Retry starts one new save request while retaining focus and stable width.

    • Save pending → Save successful

      The save request succeeds and exposes the completed result without a second activation.

    • Save successful → Save idle

      Reset restores the replayable example to its initial Save state.

    Test scenarios

    Context
    A profile form saves a display name with a primary Save changes action.
    Mission
    Activate Save with Space, verify the pending state blocks a second request, and recover from a server error.
    Primary state
    The enabled submit button has a clear label, visible focus, and sufficient text contrast.
    Edge case
    During submission, the button preserves its width, exposes Saving, and blocks duplicate activation without removing focus.

    Visual signals

    • Visible action label
    • Shape and contrast indicate interactivity
    • Primary, secondary, and disabled states share one system

    Behavioral signals

    • Enter and Space activate it
    • Disabled state prevents the action
    • Pending state prevents duplicate activation

    Accessibility

    Role
    button
    Accessible name
    The primary control or named region for Button has a stable accessible name from visible text or an explicit programmatic label; placeholder text and tooltips are not names.
    Focus
    A high-contrast focus indicator remains visible in every enabled visual variant and pending state.
    Dismissal
    Not applicable: an action button does not open a surface unless that separate relationship is defined.
    Scroll
    Activating the control with Space does not scroll the page, and feedback appears without moving focus or causing an unexpected jump.
    Announcement
    Accessible name, disabled or pressed state when applicable, and pending result are exposed without changing the label ambiguously.
    Keyboard
    • Tab focuses the button
    • Enter and Space activate it
    • Form submit behavior follows its explicit type

    Bindings

    Open the HTML, ARIA, Radix, and shadcn matrix
    • button[type=button|submit|reset]

      implementationKind
      native
      nativeElement
      button[type=button|submit|reset]
      ariaPattern
      button
      radixPrimitive
      Not applicable
      shadcnRecipe
      Not applicable
      runtimeDependency
      Not applicable
      packageName
      Not applicable
      exportName
      Not applicable
      exactVersion
      Not applicable
      status
      verified
      sourceId
      source-ui-html-button
      deprecationStatus
      active
      replacement
      Not applicable
      validFrom
      Not applicable
      validUntil
      Not applicable

      Equivalence caveat: A button performs an action. Navigation belongs to a link, and an explicit type prevents accidental form submission.

      Verify binding source

    Sources

    • WHATWG HTML: The button element
      sourceId
      source-ui-html-button
      kind
      standard
      canonicalUrl
      https://html.spec.whatwg.org/multipage/form-elements.html#the-button-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: Button: normative native semantics, states, attributes, and browser behavior for button.

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

      Claim covered: Button: informative APG guidance for the button pattern: roles, states, relationships, and keyboard interaction.

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

      Claim covered: Button: informative WCAG guidance for status messages announced without moving focus.

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