SupportingText

A small, accessible text component for labels, helpers, descriptions, and error messages around form fields.

Label is the short, descriptive caption that titles a form control — the text shown above an input, select, slider, or other control — telling the user what value is expected. It can include an optional info icon that reveals extra guidance on demand.

When to use

When you need to name a form control so users know what to enter or choose (above an input, select, slider, etc.)

When a control needs a persistent, always-visible name rather than a hint that disappears

When a field benefits from supplementary help, exposed through the optional info icon

When not to use

As a substitute for the placeholder inside a field — the label should stay visible and sit outside the control

For long instructions or help text — use helper / description text below the field instead

• As a heading for a whole section or page — use a Heading text instead
• For decorative or body text unrelated to a control — use plain Text instead

Content guidelines

Keep the label short and noun-based ("Email", "Country"), and use consistent casing across all fields.

Describe what the field is, not the action the user takes.

Mark required or optional fields consistently across the product, and never by color alone.

Use Primary for the main, default field label and Tertiary for secondary or de-emphasized labels; apply Accent (Primary only) when a label needs extra emphasis.

Keep the label itself concise and move any longer explanation behind the info icon rather than into the label text.

Behaviour guidelines

Type — Primary is the strong default treatment; Tertiary is muted for secondary contexts. The Accent variant exists for Primary only, so a Tertiary label has no accent state.

Size — XL, L, M, S, and XS scale the label to match the control it titles and the surrounding density; pair the label size with its field consistently.

Info icon — reveals supplementary guidance on hover, focus, or click; keep it optional and only for genuinely helpful context, not essential instructions.

Association — the label must sit directly above or beside its control and stay visually tied to it even when the layout wraps or scrolls.

Accessibility

Programmatically associate the label with its control (e.g. for / id or by wrapping) so screen readers announce it when the field receives focus.

Clicking or tapping the label should move focus to — or activate — its associated control.

The info icon's content must be reachable and readable by keyboard and screen reader, not available on hover alone.

Ensure contrast meets minimums for every type and size, including the muted Tertiary treatment.

Never communicate required, optional, or error state through color alone — pair it with text or an icon.

Installation

npm install @xsolla/xui-supporting-text

Imports

import { SupportingText } from '@xsolla/xui-supporting-text';

Quick start

import * as React from 'react';
import { SupportingText } from '@xsolla/xui-supporting-text';

export default function QuickStart() {
  return <SupportingText variant="helper">Helper text</SupportingText>;
}

API Reference

<SupportingText>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | children | ReactNode | - | Text content. | | variant | "label" \| "helper" \| "description" \| "error" | "helper" | Visual variant. Only error changes colour and announcement behaviour. | | size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "md" | Sizing token; resolves font size, line height, gap, and icon size via theme.sizing.supportingText. | | icon | ReactNode | - | Icon rendered after the text. | | showIcon | boolean | false | Render the icon slot. The icon is also rendered when icon is provided. | | id | string | - | HTML id for aria-describedby linking. | | aria-label | string | - | Accessible label override. | | aria-describedby | string | - | Id of an element this text describes. | | testID | string | - | Test identifier. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

Anatomy

import { SupportingText } from '@xsolla/xui-supporting-text';
import { Info } from '@xsolla/xui-icons-base';

<SupportingText
  variant="helper"
  size="md"
  icon={<Info />}
  showIcon
  id="field-hint"
>
  Helper content
</SupportingText>

Variants

| Variant | Colour | Usage | | --- | --- | --- | | label | content.tertiary | Field labels. | | helper | content.tertiary | Inline guidance and hints. | | description | content.tertiary | Additional context below a control. | | error | content.alert.primary | Validation errors. Adds role="alert" and aria-live="polite". |

Examples

All variants

import * as React from 'react';
import { SupportingText } from '@xsolla/xui-supporting-text';

export default function Variants() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <SupportingText variant="label">Label</SupportingText>
      <SupportingText variant="helper">Helper</SupportingText>
      <SupportingText variant="description">Description</SupportingText>
      <SupportingText variant="error">Error message</SupportingText>
    </div>
  );
}

Sizes

import * as React from 'react';
import { SupportingText } from '@xsolla/xui-supporting-text';

export default function Sizes() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
      <SupportingText size="xs">xs</SupportingText>
      <SupportingText size="sm">sm</SupportingText>
      <SupportingText size="md">md</SupportingText>
      <SupportingText size="lg">lg</SupportingText>
      <SupportingText size="xl">xl</SupportingText>
    </div>
  );
}

With icon

import * as React from 'react';
import { SupportingText } from '@xsolla/xui-supporting-text';
import { Info } from '@xsolla/xui-icons-base';

export default function WithIcon() {
  return (
    <SupportingText variant="helper" icon={<Info />} showIcon>
      Click here for more information
    </SupportingText>
  );
}

Form field with linked error

import * as React from 'react';
import { SupportingText } from '@xsolla/xui-supporting-text';
import { Input } from '@xsolla/xui-input';

export default function LinkedError() {
  const [email, setEmail] = React.useState('');
  const [error, setError] = React.useState('');

  const validate = (value: string) => {
    setError(value && !value.includes('@') ? 'Please enter a valid email address' : '');
  };

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
      <SupportingText variant="label" id="email-label">Email</SupportingText>
      <Input
        value={email}
        onChangeText={(text) => { setEmail(text); validate(text); }}
        aria-labelledby="email-label"
        aria-describedby={error ? 'email-error' : 'email-hint'}
        error={!!error}
      />
      {error ? (
        <SupportingText variant="error" id="email-error">{error}</SupportingText>
      ) : (
        <SupportingText variant="helper" id="email-hint">We'll never share your email</SupportingText>
      )}
    </div>
  );
}

Accessibility

• The error variant renders with role="alert" and aria-live="polite" so messages are announced when they appear.
• The explicit aria-live="polite" intentionally overrides the implicit assertive that role="alert" would otherwise apply, so error messages announce without interrupting the user's current screen reader output.
• Use id on the supporting text and reference it from the related form control's aria-describedby so the text is read together with the field.
• Icons rendered through the icon/showIcon props are marked aria-hidden; pair with descriptive text rather than relying on iconography alone.