Typography

Display and style text with consistent levels, variants, and semantic mapping.
Works with global tokens (CSS variables) and supports a unified sl={{}} style layer and the design-system CommonLayoutProps.

Aliased as Text for convenience (1:1 behavior).

---

Import

import { Typography, Text } from "@libdev-ui/base";

---

Demo

Typography demo

Levels • Variants • Colors • Decorators • Wrap • Layout props

plain / primary

soft / primary

solid / primary

outlined / primary

soft / primary.hover

plain / text.secondary

🚀

Start and end decorators with medium weight

✨

Balanced wrapping tries to distribute words more evenly across lines for nicer rhythm.

This will be truncated when too narrow.

Link as <a> element (opens libdev.net)

Uses CommonLayoutProps (responsive margin & padding)

Local sl style layer (letter-spacing, uppercase)

Text alias (same behavior as Typography)

---

Usage

TypeScript

import { Typography } from "@libdev-ui/base";

export function Example() {
  return (
    <>
      <Typography level="h3" gutterBottom>Section title</Typography>
      <Typography level="body-md" color="text.secondary">
        Supporting text using the design-system token.
      </Typography>
      <Typography variant="solid" color="primary" sl={{ borderRadius: "8px" }}>
        Solid badge-like text
      </Typography>
    </>
  );
}

JavaScript

import { Typography } from "@libdev-ui/base";

export function Example() {
  return (
    <>
      <Typography level="h3" gutterBottom>Section title</Typography>
      <Typography level="body-md" color="text.secondary">
        Supporting text using the design-system token.
      </Typography>
      <Typography variant="solid" color="primary" sl={{ borderRadius: "8px" }}>
        Solid badge-like text
      </Typography>
    </>
  );
}

---

Props

The component is polymorphic: use as or component to change the root element (e.g. "p", "label", "a").

Prop	Type	Default	Description
as / component	React.ElementType	"span"	Element for the root (polymorphic).
children	React.ReactNode	–	Content to render.
color	LDColorToken | string	–	Themed color token (e.g. primary, text.secondary, background-level1) or any CSS color/var(...).
textColor	string	–	Direct text color override (CSS).
variant	"plain" | "soft" | "solid" | "outlined"	"plain"	Visual style variant.
level	"h1" | "h2" | "h3" | "h4" | "title-lg" | "title-md" | "title-sm" | "body-lg" | "body-md" | "body-sm" | "body-xs" | "inherit"	"body-md"	Typography level controlling size/line-height (and semantic mapping by default).
levelMapping	Partial<Record<level,string|Component>>	(see table below)	Override the element for a given level.
gutterBottom	boolean	false	Adds a small bottom margin.
noWrap	boolean	false	No wrapping, ellipsis overflow.
truncate	boolean	false	Shorthand for single-line ellipsis.
wrap	"wrap" | "nowrap" | "balance" | "pretty"	"wrap"	Wrap behavior (uses modern text-wrap when supported).
align	"left" | "center" | "right" | "justify"	–	Text alignment.
weight	"light" | "regular" | "medium" | "bold" | number"	–	Font weight override.
startDecorator	React.ReactNode	–	Element placed before the text.
endDecorator	React.ReactNode	–	Element placed after the text.
slots	{ root?, startDecorator?, endDecorator? }	–	Replace internal slot elements.
slotProps	{ root?, startDecorator?, endDecorator? }	–	Props for each slot.
className	string	–	CSS class on the root.
style	React.CSSProperties	–	Inline style (final merge winner).
sl	React.CSSProperties	–	Standard style layer merged before style (same pattern as Button/Input).
...CommonLayoutProps	(see below)	–	Margin/padding/size/position/overflow/flex/grid shorthands.

CommonLayoutProps

Shorthands available on all layout-aware components:

• Margin: m, mx, my, mt, mr, mb, ml
• Padding: p, px, py, pt, pr, pb, pl
• Size: width, minWidth, maxWidth, height, minHeight, maxHeight
• Position: position, inset, top, right, bottom, left
• Overflow: overflow, overflowX, overflowY
• Flex/Grid: flexBasis, flexShrink, flexGrow, gridArea, gridColumn*, gridRow*

These props are parsed through your design-system helpers and map to CSS reliably.

---

Levels & semantic mapping

Default mapping of level → element (override with levelMapping):

Level	Element
h1	h1
h2	h2
h3	h3
h4	h4
title-lg	p
title-md	p
title-sm	p
body-lg	p
body-md	p
body-sm	p
body-xs	span
inherit	p

TypeScript

<Typography level="title-lg" levelMapping={{ "title-lg": "h3" }}>
  Section title rendered as &lt;h3&gt;
</Typography>

JavaScript

<Typography level="title-lg" levelMapping={{ "title-lg": "h3" }}>
  Section title rendered as &lt;h3&gt;
</Typography>

---

Variants

plain · soft · solid · outlined

They respect your tokens only (no hard-coded colors). For soft/outlined, backgrounds/borders are derived with color-mix() against the provided color.

TypeScript

<>
  <Typography variant="plain" color="primary">plain</Typography>
  <Typography variant="soft" color="primary">soft</Typography>
  <Typography variant="solid" color="primary">solid</Typography>
  <Typography variant="outlined" color="primary">outlined</Typography>
</>

JavaScript

<>
  <Typography variant="plain" color="primary">plain</Typography>
  <Typography variant="soft" color="primary">soft</Typography>
  <Typography variant="solid" color="primary">solid</Typography>
  <Typography variant="outlined" color="primary">outlined</Typography>
</>

---

Colors (tokens)

Use any LDColorToken like:

• primary, primary.hover
• secondary, secondary.disabled, secondary.disabledText
• text, text.secondary
• background-level0, background-level1, background-level2
• or any custom var(--...), #hex, rgb(...)

TypeScript

<>
  <Typography color="text">Default text token</Typography>
  <Typography color="text.secondary">Secondary text token</Typography>
  <Typography color="primary.hover">Primary hover token</Typography>
  <Typography color="var(--ld-color-warning)">Custom var()</Typography>
  <Typography color="#22c55e">Custom hex</Typography>
</>

JavaScript

<>
  <Typography color="text">Default text token</Typography>
  <Typography color="text.secondary">Secondary text token</Typography>
  <Typography color="primary.hover">Primary hover token</Typography>
  <Typography color="var(--ld-color-warning)">Custom var()</Typography>
  <Typography color="#22c55e">Custom hex</Typography>
</>

---

Wrapping & truncation

• wrap="wrap" | "nowrap" | "balance" | "pretty"
• noWrap / truncate add single-line ellipsis.

TypeScript

<>
  <Typography wrap="balance">
    This paragraph uses balanced wrapping for nicer line breaks.
  </Typography>
  <Typography wrap="pretty" color="text.secondary">
    Pretty wrapping prefers visually nicer break points when possible.
  </Typography>
  <Box sl={{ width: 280 }}>
    <Typography truncate title="This will be truncated">
      This will be truncated
    </Typography>
  </Box>
</>

JavaScript

<>
  <Typography wrap="balance">
    This paragraph uses balanced wrapping for nicer line breaks.
  </Typography>
  <Typography wrap="pretty" color="text.secondary">
    Pretty wrapping prefers visually nicer break points when possible.
  </Typography>
  <Box sl={{ width: 280 }}>
    <Typography truncate title="This will be truncated">
      This will be truncated
    </Typography>
  </Box>
</>

---

Decorators & slots

TypeScript

<>
  <Typography startDecorator="New:" endDecorator="→">
    Inline decorators
  </Typography>

  <Typography
    startDecorator="New:"
    slots={{ startDecorator: "strong" }}
    slotProps={{ startDecorator: { style: { color: "var(--ld-color-warning)" } } }}
  >
    Custom startDecorator slot element
  </Typography>
</>

JavaScript

<>
  <Typography startDecorator="New:" endDecorator="→">
    Inline decorators
  </Typography>

  <Typography
    startDecorator="New:"
    slots={{ startDecorator: "strong" }}
    slotProps={{ startDecorator: { style: { color: "var(--ld-color-warning)" } } }}
  >
    Custom startDecorator slot element
  </Typography>
</>

---

Text alias

Text is an alias for Typography:

TypeScript

import { Text } from "@libdev-ui/base";

<Text level="body-sm" color="success" variant="outlined">
  Text alias (same behavior)
</Text>

JavaScript

import { Text } from "@libdev-ui/base";

<Text level="body-sm" color="success" variant="outlined">
  Text alias (same behavior)
</Text>

---

Accessibility

• Semantic mapping ensures proper heading structure when using level="h1|h2|h3|h4".
• Use as="label" when labelling form controls, or as="a" for links (with proper href, target, rel).

info

Typography has no role by default; it adopts the semantics of the chosen element. Prefer meaningful elements (p, label, h*, a) over plain span.