Text

Import: import { Text, type TextProps, type TextFont, type TextColor } from "@opal/components";

A styled text component with string-enum props for font preset and color selection. Supports inline markdown rendering via RichStr — pass markdown("*bold* text") as children to enable.

Props

No className or style. Text strips both (its props extend WithoutStyles); every aspect of its appearance is driven by font, color, nowrap, and maxLines. For layout concerns (margin, flex, width, alignment) wrap Text in a container or move the utility class to the parent — don't reach for className. All other HTML attributes (id, onClick, title, aria-*, data-*) pass straight through to the rendered element.

TextFont

TextColor

Default: "text-04". Within each numbered scale, 05 is the strongest/most prominent and lower numbers are progressively fainter.

Usage Examples

import { Text } from "@opal/components";

// Basic
<Text font="main-ui-body" color="text-03">
  Hello world
</Text>

// Heading
<Text font="heading-h2" color="text-05" as="h2">
  Page Title
</Text>

// Inverted (for dark backgrounds)
<Text font="main-ui-body" color="text-inverted-05">
  Light text on dark
</Text>

// As paragraph
<Text font="main-content-body" color="text-03" as="p">
  A full paragraph of text.
</Text>

Inline Markdown via RichStr

Inline markdown is opt-in via the markdown() function, which returns a RichStr. When Text receives a RichStr as children, it parses the inner string as inline markdown. Plain strings are rendered as-is — no parsing, no surprises. Text does not accept arbitrary JSX as children; every non-string child must be branded via markdown() or richNodes().

import { Text } from "@opal/components";
import { markdown } from "@opal/utils";

// Inline markdown — bold, italic, links, code, strikethrough
<Text font="main-ui-body" color="text-05">
  {markdown("*Hello*, **world**! Visit [Onyx](https://onyx.app) and run `onyx start`.")}
</Text>

// Plain string — no markdown parsing
<Text font="main-ui-body" color="text-03">
  This *stays* as-is, no formatting applied.
</Text>

Supported syntax: **bold**, *italic*, `code`, [link](url), ~~strikethrough~~, \n (newline → ).

Markdown rendering uses react-markdown internally, restricted to inline elements only. http(s) links open in a new tab; mailto: and tel: links open natively. Inline code inherits the parent font size and switches to the monospace family.

Newlines (\n) are converted to elements that inherit the parent's line-height, so line spacing is proportional to the font size. For full block-level markdown (code blocks, headings, lists), use MinimalMarkdown instead.

Using RichStr in component props

Components that want to support optional markdown in their text props should accept string | RichStr:

import type { RichStr } from "@opal/types";

interface MyComponentProps {
  title: string | RichStr;
  description?: string | RichStr;
}

This avoids API coloring — no markdown boolean needs to be threaded through intermediate components. The decision to use markdown lives at the call site.

Inline React nodes via RichNodes

Some sentences must embed an inline component — most often i18n rich text, where a translated sentence wraps part of itself in a link or button (next-intl t.rich). Markdown cannot express an element with an event handler, so for this case richNodes() brands a ReactNode as deliberate Text children:

import { Text } from "@opal/components";
import { richNodes } from "@opal/utils";

<Text font="main-ui-body" color="text-04">
  {richNodes(
    t.rich("waitingOnVerification.helpPrompt.text", {
      link: (chunks) => (
        <RequestNewVerificationEmail email={email}>{chunks}</RequestNewVerificationEmail>
      ),
    })
  )}
</Text>

The nodes render verbatim and inherit the font and color presets. The brand keeps the same discipline as RichStr: naked JSX children stay a type error, and the opt-in is visible and greppable at the call site.

Rules of thumb:

• Prefer a plain string; use markdown() when the formatting is static (bold, code, plain links); use richNodes() only when a real component must sit mid-sentence.
• Keep the content inline (spans, links, buttons) — never layout JSX.
• RichNodes is accepted only by Text children. Props typed string | RichStr (title, description, tooltip, …) must stay plain-string-derivable for truncation and aria labels, so do not widen them.

Compatibility

@/refresh-components/texts/Text is an independent legacy component that implements the same font/color presets via a boolean-flag API. It is not a wrapper around this component. New code should import directly from @opal/components.