Text

Semantic typography primitive with variant/tone styling that honors OS/browser font scaling.

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: Data display
• 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/text.tsx

Import

import { Text, textVariants } from '@beemvp/beeui-ui';

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

pnpm beeui add text

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: Text textVariants
  • Also routed here, outside the Registry family:
    • FontFamily
    • NumericVariant
    • semanticTypographyClasses
    • text
  • Package export subpath: @beemvp/beeui-ui/text

Exported types: TextProps

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 semantic typography primitive; variant/tone apply typed styling, and text always honors OS/browser font scaling — BeeUI never sets allowFontScaling={false}.

Props

TextProps

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.
family	'mono'	—	'mono' renders the text in the system-monospace fallback stack (e.g. for reference codes/IDs). Opt-in only — omitting it preserves the inherited sans/system font.
numeric	'tabular'	—	'tabular' opts numeric content into equal-width figures so columns of amounts/KPIs/timers align. Omit for normal proportional figures.
tone	'default' | 'muted' | 'subtle' | 'primary' | 'destructive' | 'success' | 'warning' | 'info'	'default'	Chooses this element’s tone from textVariants’s presets, declared in packages/ui/src/components/text.tsx — the classes each value applies are there.
variant	'display' | 'title' | 'heading' | 'body' | 'label' | 'caption'	'body'	Chooses this element’s variant from textVariants’s presets, declared in packages/ui/src/components/text.tsx — the classes each value applies are there.

Also carries every prop of RNTextProps — that upstream contract is 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, 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, but its source branches on Platform, so some behavior differs by target.

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 text.tsx.
• Accessibility states and properties it sets: none set in text.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: tone (8 values), variant (6 values) — the values are in the props tables above.
• 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__/accessibility-readonly.test.tsx
• Additional fixture: apps/showcase/__tests__/component-contracts.test.tsx
• Additional fixture: apps/showcase/__tests__/data-typography.test.tsx
• Additional fixture: apps/showcase/__tests__/dynamic-type-contract.test.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: Text
  • Public composition parts / helpers:
    • textVariants
  • Exported type surface:
    • TextProps

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

These are the parts of the typechecked runtime Showcase fixture behind this live preview — apps/showcase/component-gallery/component-gallery.tsx, 1103 lines — where Text is actually used: 59 lines in 6 places, of 11 in total — open the fixture for the remaining 5. Each block is copied verbatim from the line range named above it, so it is the same executable source, not a retelling of it. Other uses of this family, and the parts of the file exercising other families, are not reproduced here.

Imports the examples below need (a filtered subset of the fixture’s own top-level imports):

import { Badge, Box, Button, Card, EmptyState, ErrorState, Progress, Separator, Skeleton, Spinner, Switch, Text, VStack } from '@beemvp/beeui-ui';
import * as React from 'react';

Placeholder for a prop this fixture receives (not fixture source — substitute your own handler):

const children: string = undefined as never;
const description: string = undefined as never;

lines 141–144:

    <VStack gap="xs">
      <Text variant="heading">{children}</Text>
      <Text tone="muted">{description}</Text>
    </VStack>

lines 547–565:

            <Card className="gap-4" variant="muted">
              <Text variant="heading">Status and feedback</Text>
              <Box className="flex-row flex-wrap gap-2">
                <Badge>Primary</Badge>
                <Badge variant="secondary">Secondary</Badge>
                <Badge variant="success">Success</Badge>
                <Badge variant="warning">Warning</Badge>
                <Badge variant="destructive">Error</Badge>
                <Badge variant="info">Info</Badge>
              </Box>
              <Separator />
              <Box className="flex-row items-center gap-5">
                <Spinner testID="spinner-default" />
                <Spinner tone="success" />
                <Spinner tone="warning" />
                <Spinner testID="spinner-destructive" tone="destructive" />
              </Box>
              <Progress accessibilityLabel="Profile completion" value={72} />
            </Card>

lines 569–590:

            <Card className="gap-4">
              <Text variant="heading">Loading and state surfaces</Text>
              <Box className="flex-row items-center gap-3">
                <Skeleton className="h-12 w-12" variant="circle" />
                <Box className="flex-1 gap-2">
                  <Skeleton className="w-2/3" variant="text" />
                  <Skeleton className="w-full" variant="text" />
                </Box>
              </Box>
              <Skeleton className="h-24 w-full" />
              <Separator />
              <EmptyState
                action={<Button size="sm">Create record</Button>}
                description="Create your first record to get started."
                title="No records yet"
              />
              <Separator />
              <ErrorState
                action={<Button size="sm" variant="outline">Try again</Button>}
                description="The server could not load this section."
              />
            </Card>

Fixture state this block reads (same file, line 461):

  const [notifications, setNotifications] = React.useState(true);

lines 665–672:

              <Box className="flex-row items-center justify-between gap-4">
                <Text>Notifications</Text>
                <Switch
                  accessibilityLabel="Notifications"
                  onValueChange={setNotifications}
                  value={notifications}
                />
              </Box>

Fixture state this block reads (same file, lines 469, 470, 471):

  const [menuToolbar, setMenuToolbar] = React.useState(true);
  const [menuDensity, setMenuDensity] = React.useState('comfortable');
  const [menuAction, setMenuAction] = React.useState('No action yet');

lines 820–822:

                  <Text tone="muted">
                    {`Last action: ${menuAction} · toolbar ${menuToolbar ? 'on' : 'off'} · ${menuDensity}`}
                  </Text>

lines 1085–1087:

              <Text tone="muted" variant="caption">
                Navigation remains application-owned. This showcase intentionally has no router or docs-site framework.
              </Text>

Open the fixture itself for the full surrounding component. For a smaller app-specific example, start from the imports and fixture-state blocks above and keep only the state your screen owns.

Limitations

family accepts only the monospace value — there is no sans value that would reset an inherited font family — and numeric only the tabular one. Both resolve through utility classes on Web and through React Native style props on native, so no inline font style is emitted on Web.

Implementation note: Each variant maps to a fixed fontSize/lineHeight step from the token scale — see the typography scale table for the full variant ↔ size/line-height/weight mapping. There is no separate numeric scale to read at runtime; variant is the only entry point.

Related

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