FormStatus

Polite live feedback for validation, progress and completed form actions.

FormStatus

View source ยท API reference

Change the feedback

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

<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'

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 />` },
)

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>

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.