Typography

A cross-platform text component with predefined style variants, themed colours, and product-context-aware sizing.

Installation

npm install @xsolla/xui-typography

Imports

import { Typography } from "@xsolla/xui-typography";

Quick start

import * as React from "react";
import { Typography } from "@xsolla/xui-typography";

export default function QuickStart() {
  return <Typography variant="bodyMd">Hello world</Typography>;
}

API Reference

<Typography>

| Prop | Type | Default | Description | | ---------------- | --------------------------------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | testID | string | — | Test ID for testing frameworks. On web this renders as data-testid; on React Native it renders as testID. | | children | ReactNode | - | Text content. | | variant | VariantType | "bodyMd" | Text style variant (see below). | | color | ColorType \| string | "inherit" | Themed colour token, or a custom CSS colour string. | | align | "left" \| "center" \| "right" \| "justify" \| "inherit" | "inherit" | Text alignment. | | noWrap | boolean | false | Single-line truncation with ellipsis. | | marginTop | number | 0 | Top margin in pixels. | | marginBottom | number | 0 | Bottom margin in pixels. | | as | ElementType | Auto-mapped for headings | HTML element to render (web only). Heading variants (h1-h5) automatically render as semantic HTML elements (<h1>-<h5>). Can be overridden for any variant. | | productContext | "b2c" \| "b2b" \| "paystation" \| "presentation" | - | Override the product context for this instance only. | | aria-hidden | boolean | - | Hide from assistive technology. | | aria-live | "polite" \| "assertive" \| "off" | - | Live-region politeness. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

VariantType

type VariantType =
  | "display"
  | "h1"
  | "h2"
  | "h3"
  | "h4"
  | "h5"
  | "bodyLg"
  | "bodyLgAccent"
  | "bodyLgParagraph"
  | "bodyMd"
  | "bodyMdAccent"
  | "bodyMdParagraph"
  | "bodySm"
  | "bodySmAccent"
  | "bodySmParagraph"
  | "bodyXs"
  | "bodyXsAccent"
  | "bodyXsParagraph"
  | "bodyXxs"
  | "bodyXxsAccent"
  | "bodyXxsParagraph";

*Accent variants use weight 500. *Paragraph variants use a relaxed line height suitable for long-form copy.

ColorType

type ColorType =
  | "inherit"
  | "primary"
  | "secondary"
  | "tertiary"
  | "brand"
  | "brandSecondary"
  | "success"
  | "warning"
  | "alert"
  | "neutral";

color also accepts any string (for example, a hex or CSS variable) for custom colours.

Examples

Headings

import * as React from "react";
import { Typography } from "@xsolla/xui-typography";

export default function Headings() {
  return (
    <div>
      <Typography variant="display">Display</Typography>
      <Typography variant="h1">Heading 1</Typography>
      <Typography variant="h2">Heading 2</Typography>
      <Typography variant="h3">Heading 3</Typography>
      <Typography variant="h4">Heading 4</Typography>
      <Typography variant="h5">Heading 5</Typography>
    </div>
  );
}

Body and accent

import * as React from "react";
import { Typography } from "@xsolla/xui-typography";

export default function Body() {
  return (
    <div>
      <Typography variant="bodyLg">Large body</Typography>
      <Typography variant="bodyLgAccent">Large body accent</Typography>
      <Typography variant="bodyMd">Medium body (default)</Typography>
      <Typography variant="bodyMdParagraph">Medium body paragraph</Typography>
      <Typography variant="bodyXxs">Extra-extra-small body</Typography>
    </div>
  );
}

Colours

import * as React from "react";
import { Typography } from "@xsolla/xui-typography";

export default function Colours() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: 4 }}>
      <Typography color="primary">Primary</Typography>
      <Typography color="secondary">Secondary</Typography>
      <Typography color="tertiary">Tertiary</Typography>
      <Typography color="brand">Brand</Typography>
      <Typography color="success">Success</Typography>
      <Typography color="warning">Warning</Typography>
      <Typography color="alert">Alert</Typography>
    </div>
  );
}

Truncation

import * as React from "react";
import { Typography } from "@xsolla/xui-typography";

export default function Truncation() {
  return (
    <div style={{ width: 200 }}>
      <Typography variant="bodyMd" noWrap>
        This long text will be truncated with an ellipsis.
      </Typography>
    </div>
  );
}

Product context override

import * as React from "react";
import { Typography } from "@xsolla/xui-typography";
import { XUIProvider } from "@xsolla/xui-core";

export default function ContextOverride() {
  return (
    <XUIProvider initialProductContext="b2b">
      <Typography variant="h1">Default (B2B from provider)</Typography>
      <Typography variant="h1" productContext="b2c">
        B2C override
      </Typography>
      <Typography variant="h1" productContext="paystation">
        PayStation override
      </Typography>
    </XUIProvider>
  );
}

Semantic HTML

Heading variants automatically render as semantic HTML for accessibility and SEO:

import * as React from "react";
import { Typography } from "@xsolla/xui-typography";

export default function SemanticHeadings() {
  return (
    <article>
      <Typography variant="h1">Main Article Title</Typography>
      <Typography variant="bodyMdParagraph">
        This is the introduction paragraph.
      </Typography>

      <Typography variant="h2">Section Title</Typography>
      <Typography variant="bodyMdParagraph">
        This section contains important content.
      </Typography>

      <Typography variant="h3">Subsection</Typography>
      <Typography variant="bodyMd">Some additional details.</Typography>
    </article>
  );

  // Renders as:
  // <article>
  //   <h1 class="...">Main Article Title</h1>
  //   <p class="...">This is the introduction paragraph.</p>
  //   <h2 class="...">Section Title</h2>
  //   <p class="...">This section contains important content.</p>
  //   <h3 class="...">Subsection</h3>
  //   <span class="...">Some additional details.</span>
  // </article>
}

You can override the default element with the as prop:

// Render h1 styling as a div instead of h1
<Typography variant="h1" as="div">
  Styled as heading but rendered as div
</Typography>

Behaviour

• Resolved sizes, weights, and line heights come from the active product context. With no override, the provider's initialProductContext (defaulting to b2b) is used.
• The Accent family raises weight to 500; Paragraph family raises line height for readable long-form copy.
• as is web-only; on native platforms the rendered element is fixed.

Accessibility

• Heading variants (h1-h5) automatically render as semantic HTML elements (<h1>-<h5>) for proper document structure and screen reader navigation.
• Use heading variants in document order to create a logical heading hierarchy.
• Body variants render as <span> by default; use the as prop to render as <p> for paragraph text or other semantic elements as needed.
• aria-live is available for live-region announcements when content updates dynamically.
• Avoid using noWrap on copy that the user must read in full; prefer wrapping or a tooltip for the truncated value.