Field Group

A cross-platform React wrapper component that adds consistent labeling, required indicators, helper text, and spacing to form fields.

Installation

npm install @xsolla/xui-field-group
# or
yarn add @xsolla/xui-field-group

Demo

Basic Field Group

import * as React from 'react';
import { FieldGroup } from '@xsolla/xui-field-group';
import { Input } from '@xsolla/xui-input';

export default function BasicFieldGroup() {
  return (
    <FieldGroup label="Username">
      <Input placeholder="Enter username" />
    </FieldGroup>
  );
}

Required Field

import * as React from 'react';
import { FieldGroup } from '@xsolla/xui-field-group';
import { Input } from '@xsolla/xui-input';

export default function RequiredField() {
  return (
    <FieldGroup label="Email" required>
      <Input type="email" placeholder="Enter email" />
    </FieldGroup>
  );
}

With Helper Text

import * as React from 'react';
import { FieldGroup } from '@xsolla/xui-field-group';
import { Input } from '@xsolla/xui-input';

export default function HelperField() {
  return (
    <FieldGroup
      label="Password"
      helper="Must be at least 8 characters"
    >
      <Input type="password" placeholder="Enter password" />
    </FieldGroup>
  );
}

With Icon

import * as React from 'react';
import { FieldGroup } from '@xsolla/xui-field-group';
import { Input } from '@xsolla/xui-input';
import { Info } from '@xsolla/xui-icons-base';

export default function IconField() {
  return (
    <FieldGroup
      label="API Key"
      icon={<Info />}
    >
      <Input placeholder="Enter API key" />
    </FieldGroup>
  );
}

Anatomy

import { FieldGroup } from '@xsolla/xui-field-group';

<FieldGroup
  label="Field Label"          // Label text
  required={false}             // Show required asterisk
  helper="Helper text"         // Helper text below field
  icon={<Icon />}              // Icon next to label
  size="md"                    // Size variant
  marginBottom={16}            // Bottom margin (spacing)
  htmlFor="field-id"           // Associate with form field
>
  <FormField />                // Form control component
</FieldGroup>

Examples

Form with Field Groups

import * as React from 'react';
import { FieldGroup } from '@xsolla/xui-field-group';
import { Input } from '@xsolla/xui-input';
import { Select } from '@xsolla/xui-select';
import { Textarea } from '@xsolla/xui-textarea';
import { Button } from '@xsolla/xui-button';

export default function CompleteForm() {
  return (
    <div style={{ maxWidth: 400 }}>
      <FieldGroup label="Full Name" required>
        <Input placeholder="John Doe" />
      </FieldGroup>
      <FieldGroup label="Email" required helper="We'll never share your email">
        <Input type="email" placeholder="[email protected]" />
      </FieldGroup>
      <FieldGroup label="Country">
        <Select
          options={['United States', 'Canada', 'United Kingdom']}
          placeholder="Select country"
        />
      </FieldGroup>
      <FieldGroup label="Bio" helper="Max 500 characters">
        <Textarea placeholder="Tell us about yourself" />
      </FieldGroup>
      <FieldGroup marginBottom={0}>
        <Button>Submit</Button>
      </FieldGroup>
    </div>
  );
}

Field Group Sizes

import * as React from 'react';
import { FieldGroup } from '@xsolla/xui-field-group';
import { Input } from '@xsolla/xui-input';

export default function FieldGroupSizes() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
      <FieldGroup size="sm" label="Small Field" required helper="Small helper">
        <Input size="sm" placeholder="Small input" />
      </FieldGroup>
      <FieldGroup size="md" label="Medium Field" required helper="Medium helper">
        <Input size="md" placeholder="Medium input" />
      </FieldGroup>
      <FieldGroup size="lg" label="Large Field" required helper="Large helper">
        <Input size="lg" placeholder="Large input" />
      </FieldGroup>
    </div>
  );
}

API Reference

FieldGroup

FieldGroup Props:

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | children | ReactNode | - | Form field component. | | label | string | - | Label text. | | required | boolean | false | Show required asterisk (*). | | helper | string | - | Helper text below field. | | icon | ReactElement | - | Icon next to label. | | size | "sm" \| "md" \| "lg" | "md" | Size variant. | | marginBottom | number | Based on size | Bottom margin for spacing. | | htmlFor | string | - | Associate label with field by ID. | | data-testid | string | - | Test identifier. |

Size Specifications

| Size | Label Font | Label Line Height | Helper Font | Margin Bottom | | :--- | :--------- | :---------------- | :---------- | :------------ | | sm | 10px | 16px | 12px | 8px | | md | 12px | 20px | 12px | 16px | | lg | 14px | 24px | 12px | 24px |

Behavior

• Required asterisk (*) appears before label in red
• Icon appears after label with appropriate spacing
• Helper text appears below the field content
• Consistent vertical rhythm with configurable margins