Site color

Choose your site’s color palette.

Saved on this device.

FormStatus

FormStatusLive feedback

Keep the outcome close to the task. Polite live feedback for progress, validation, and completed actions.

Forms & input

Change the feedback

The same mounted status region receives new text. Clear hides it until there is another message.

FormStatus in contextCOMPOSITION

Choose a success or validation message, then clear it. New content is announced politely.

<RegorApp id="form-status-demo" src="./playground.ts"/>
import {
  defineButtonComponents,
  defineFlexComponents,
  defineFormComponents,
} from '@purestack/ts-components'
import type { SemanticTone } from '@purestack/ts-style'
import { createApp, defineComponent, html, type Ref, ref } from 'regor'
import { mountFormAppearanceGalleries } from '../appearance'

export interface FormStatusExample {
  statusMessage: Ref<string>
  statusTone: Ref<SemanticTone>
  showSuccess: () => void
  showError: () => void
  clear: () => void
}

const formStatusExampleTemplate = html`<Flex direction="column">
  <Flex wrap="true">
    <Btn tone="success" @click="showSuccess">Save local draft</Btn>
    <Btn tone="danger" variant="outline" @click="showError">
      Show validation error
    </Btn>
    <Btn variant="link" @click="clear">Clear message</Btn>
  </Flex>
  <FormStatus :tone="statusTone" :hidden="!statusMessage">
    {{ statusMessage }}
  </FormStatus>
</Flex>`

function createFormStatusExample(): FormStatusExample {
  const statusMessage = ref('Choose an action to see its feedback.')
  const statusTone = ref<SemanticTone>('info')
  return {
    statusMessage,
    statusTone,
    showSuccess: () => {
      statusTone('success')
      statusMessage('Draft saved in this example.')
    },
    showError: () => {
      statusTone('danger')
      statusMessage('Enter a project name before continuing.')
    },
    clear: () => statusMessage(''),
  }
}

const component = defineComponent<FormStatusExample>(
  formStatusExampleTemplate,
  {
    context: createFormStatusExample,
  },
)

createApp(
  {
    components: {
      FormStatusExample: component,

      ...defineFlexComponents(),
      ...defineButtonComponents(),
      ...defineFormComponents(),
    },
  },
  { selector: 'app#form-status-demo', template: html`<FormStatusExample/>` },
)

mountFormAppearanceGalleries()

A persistent explanation

Static supporting information can also use the status surface.

Review the entered values before submitting this form.
<FormStatus tone="warning" variant="outline">
  Review the entered values before submitting this form.
</FormStatus>

All semantic tones

All ten tones are visible at once. The control’s label and content explain the intent independently of color.

All ten semantic tonesCOMPOSITION

Compare every treatment together. Switch the site theme to see both palettes; the working status demo above shows live updates.

All visual variants

All eighteen supported treatments, shown in accent. Tone and variant are independent, so any treatment can be combined with a semantic tone.

All eighteen visual variantsCOMPOSITION

Compare every treatment together. Switch the site theme to see both palettes; the working status demo above shows live updates.

Visible and hidden feedback

hidden is a boolean that removes the status from display. The live demo above adds, changes, and clears messages. Keep status updates concise.

Visible and hidden feedbackCOMPOSITION
Visible
Review the required fields.
Hidden

The status below is intentionally absent.

Compare all values together. Use the live examples for application state and event handling.

Behavior and accessibility

The root has role status and aria-live polite. Avoid duplicating the same message in multiple live regions. Hidden suppresses both visual and accessibility-tree output; keep field-specific errors associated with their fields as well.

API reference

FormStatus contract

Props below are the public template API. RefOrValue accepts a literal or a reactive ref; bind refs with a colon-prefixed attribute. Native attributes and events can be passed through the component root.

tone

RefOrValue<SemanticTone>
Default
inherited

Semantic intent: neutral, accent, secondary, info, success, warning, danger, feature, custom or ghost. The active skin supplies the colors.

variant

RefOrValue<ComponentVariant>
Default
surface

Visual treatment. Accepts solid, surface, surfaceAlt, spotlight, glass, flat, flatAlt, flatSolid, outlineFill, outline, subtle, subtleBtn, link, sheen, underline, rail, bracket or none.

hidden

RefOrValue<boolean>
Default
false

Native hidden state. Bind a boolean to hide the region when no feedback is available.

Composition

Default slot: feedback content. Register defineFormComponents. This component announces content but does not validate or submit a form.