Form Message

Destructive form feedback (with muted HelperText variant) using polite live-region semantics.

Distribution status

BeeUI 0.86.2-rc.3 is public on npm under the opt-in next dist-tag (observed 2026-09-25T06:25:18.371Z). latest currently resolves to 0.86.2-rc.3 and lags next until the owner moves it for all four packages. See Start for the full install commands. The import shape below works against the published package; the repository-local Registry command remains available as a no-registry-required alternative from a BeeUI checkout. Pin @0.86.2-rc.3 instead of @next for an immutable version in CI.

Identity

• Category: Forms & selection
• Status: stable public Registry/export-map component family
• Targets: iOS · Android · Web, subject to the compatibility contract
• Prerequisites: @beemvp/beeui-ui installed (or this component’s source copied via the Registry CLI below) and, on Web, the BeeUI Tailwind/Uniwind theme CSS loaded — see Start for full platform setup.
• Source: packages/ui/src/components/form-message.tsx

Import

import { FormMessage, HelperText } from '@beemvp/beeui-ui';

There is no documented deep/private source import. For source ownership from a BeeUI checkout:

pnpm beeui add form-message

Registry (used throughout this page) is BeeUI’s source-ownership manifest — registry/registry.json — that the pnpm beeui/@beemvp/beeui-cli CLI reads to copy a component’s real source into your app and rewrite its internal imports; it is not an npm package index. This component’s own Registry entry: registry/registry.json.

Composition and public API

• Family exports: FormMessage HelperText
  • Also routed here, outside the Registry family:
    • form-message
  • Package export subpath: @beemvp/beeui-ui/form-message

Exported types: FormMessageProps, HelperTextProps

The generated API inventory is mechanically joined to packages/ui/src/index.ts, Registry metadata, and the component reference contract. Each type’s field table below is parsed directly from that source, not a second hand-maintained copy; for the fuller behavior narrative see the canonical component behavior catalog.

State and behavior contract

Stateless destructive form-feedback text with polite live-region semantics by default; it renders the muted HelperText variant when not carrying an active error.

Props

FormMessageProps

Prop	Type	Default	Description
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Also carries every prop of Omit<TextProps, 'tone' | 'variant'> — documented on the Text page, not reproduced here.

HelperTextProps

Prop	Type	Default	Description
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Also carries every prop of Omit<TextProps, 'tone' | 'variant'> — documented on the Text page, not reproduced here.

The executable fixtures below are the source-grounded usage examples; consumers should not infer state ownership from DOM structure or another UI library.

Provider and dependencies

• No additional provider is required by this family. BeeUIProvider remains the recommended application root.
• Peer/native dependencies visible to this Registry item: react, react-native
• Registry dependency closure: core-cn, text, theme
• Safe-area ownership remains explicit: shell surfaces touching system edges opt into SafeArea; components do not silently invent app-shell insets.
• Web consumers load the BeeUI semantic theme CSS as documented in Web onboarding.

Platform behavior

This family ships no platform-specific file, and its own source takes no Platform branch.

The same public family is exposed across the supported target matrix; meaningful platform differences remain governed by the compatibility contract.

Evidence classes are not equal and this page does not blur them: Web behavior is exercised in a real browser, while iOS and Android carry package/export and native-compile evidence, which is not device-runtime proof. The compatibility contract records which class each claim rests on.

Accessibility

• Roles this family assigns: none set in form-message.tsx.
• Accessibility states and properties it sets: accessibilityLiveRegion — read from form-message.tsx.

Keyboard/focus behavior, announcements, Dynamic Type/Web zoom, RTL and reduced-motion expectations are not derived here — see Accessibility overview, Keyboard & focus, RTL/localization and Large text & zoom. BeeUI does not claim universal accessibility certification from automated tests.

Styling and theming

• Style axes: none of its own — its appearance comes from tokens and your own classes; it also carries RNTextProps.
• Class-name surfaces: className.

Colors, spacing and typography come from semantic tokens rather than from values written here — see Theming and Density. A className is an escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Executable examples

• Primary executable fixture: apps/showcase/__tests__/application-primitives.test.tsx
• Additional fixture: apps/showcase/component-gallery/public-doc-fixtures.tsx

Addressable examples

Each link below opens the Showcase at that exact example, not at the top of the gallery:

• basic — smallest meaningful complete usage

The Showcase links demonstrate Web behavior; use the native-preview guide for real simulator/emulator/device paths.

Live Web preview

This frame loads the real BeeUI Web Showcase on demand; it is not a second docs-only implementation. It proves browser behavior only. Use native preview for iOS/Android simulator, emulator or device paths.

Composition anatomy

• Family root / primary export: FormMessage
  • Public composition parts / helpers:
    • HelperText
  • Exported type surface:
    • FormMessageProps
    • HelperTextProps

The tree above is ordinary document structure so it remains readable with keyboard and assistive technology; it is derived from the real public export family rather than a canvas-only diagram.

Verified example source

The following is the exact typechecked runtime Showcase fixture selected for this live preview: apps/showcase/component-gallery/public-doc-fixtures.tsx. Runtime gallery/pattern sources are preferred over test harnesses, and the displayed source and executable source are the same file; there is no separately maintained demo snippet.

import {
  Calendar,
  Card,
  FormMessage,
  Label,
  MetadataRow,
  Section,
  Text,
  useBeeToken,
  VisuallyHidden,
  VStack,
} from '@beemvp/beeui-ui';
import * as React from 'react';

/**
 * Small runtime surface for public families that are otherwise consumed only by
 * tests, private composition internals, or generated docs. Keeping these here
 * gives the public docs a real, typechecked Showcase source instead of falling
 * back to test/mock files.
 */
export function PublicDocFixtures() {
  const [date, setDate] = React.useState({ day: 3, month: 9, year: 2026 });
  const primary = useBeeToken('colors.primary');

  return (
    <VStack gap="lg" testID="public-doc-fixtures">
      <Card className="gap-4" padding="lg">
        <Section
          description="Public primitives that are normally embedded in larger application compositions."
          title="Documentation runtime fixtures"
        >
          <VStack gap="sm">
            <Label required>Project name</Label>
            <FormMessage>Example validation message</FormMessage>
            <MetadataRow
              description="Read through useBeeToken from the active Uniwind theme."
              label="colors.primary"
              value={String(primary)}
            />
            <Text testID="use-bee-token-value">
              {`useBeeToken('colors.primary') resolves to ${String(primary)} for the active theme.`}
            </Text>
            <Text>
              Visible companion text for the assistive-only content rendered immediately after it.
            </Text>
            <VisuallyHidden>
              <Text>Assistive-only VisuallyHidden fixture</Text>
            </VisuallyHidden>
          </VStack>
        </Section>
      </Card>

      <Card className="gap-4" padding="lg">
        <Section
          description="Standalone controlled Calendar using the same public API consumed by date-picker compositions."
          title="Calendar"
        >
          <Calendar onValueChange={setDate} value={date} />
        </Section>
      </Card>
    </VStack>
  );
}

Use the code block’s copy affordance to copy the exact fixture. For a smaller app-specific example, start from the public imports shown above and keep only the state your screen owns.

Limitations

Tone and typography variant are not accepted: FormMessage is always destructive caption text and HelperText always muted caption text. Neither associates itself with a control — that link has to be made by the caller.

Related

• All components
• Production patterns
• Showcase
• CLI & source ownership
• Source