title: Uploader subtitle: File upload component. description: A cross-platform React file uploader component with file selection, preview, and management capabilities.

Uploader

A cross-platform React file uploader component that provides a button to select files, displays selected files, and allows removing them.

Installation

npm install @xsolla/xui-uploader
# or
yarn add @xsolla/xui-uploader

Demo

Basic Uploader

import * as React from 'react';
import { Uploader } from '@xsolla/xui-uploader';

export default function BasicUploader() {
  return (
    <Uploader
      label="Upload file"
      onFilesChange={(files) => console.log('Selected:', files)}
    />
  );
}

Multiple Files

import * as React from 'react';
import { Uploader } from '@xsolla/xui-uploader';

export default function MultipleFiles() {
  return (
    <Uploader
      label="Upload documents"
      placeholder="Select multiple files"
      multiple
      onFilesChange={(files) => console.log('Files:', files)}
    />
  );
}

Accept Specific Types

import * as React from 'react';
import { Uploader } from '@xsolla/xui-uploader';

export default function ImageUploader() {
  return (
    <Uploader
      label="Upload image"
      placeholder="Select image file"
      accept=".jpg,.jpeg,.png,.gif"
      onFilesChange={(files) => console.log('Images:', files)}
    />
  );
}

Anatomy

import { Uploader } from '@xsolla/xui-uploader';

<Uploader
  label="Label"                     // Label above button
  placeholder="Select files"        // Button text
  accept=".pdf,.doc"                // Accepted file types
  multiple={false}                  // Allow multiple selection
  disabled={false}                  // Disabled state
  size="md"                          // Button size
  onFilesChange={handleFiles}       // File change callback
/>

Examples

Document Upload

import * as React from 'react';
import { Uploader } from '@xsolla/xui-uploader';

export default function DocumentUpload() {
  const [files, setFiles] = React.useState<File[]>([]);

  return (
    <div>
      <Uploader
        label="Legal documents"
        placeholder="Upload PDF documents"
        accept=".pdf"
        multiple
        onFilesChange={setFiles}
      />
      {files.length > 0 && (
        <p style={{ marginTop: 8 }}>
          {files.length} file(s) selected
        </p>
      )}
    </div>
  );
}

Profile Image Upload

import * as React from 'react';
import { Uploader } from '@xsolla/xui-uploader';

export default function ProfileImageUpload() {
  const handleImageUpload = (files: File[]) => {
    if (files.length > 0) {
      const file = files[0];
      // Create preview URL
      const previewUrl = URL.createObjectURL(file);
      console.log('Preview:', previewUrl);
    }
  };

  return (
    <div style={{ maxWidth: 300 }}>
      <Uploader
        label="Profile picture"
        placeholder="Choose image"
        accept="image/*"
        onFilesChange={handleImageUpload}
        size="sm"
      />
      <p style={{ fontSize: 12, color: '#666', marginTop: 4 }}>
        Recommended: Square image, at least 200x200px
      </p>
    </div>
  );
}

Form with File Upload

import * as React from 'react';
import { Uploader } from '@xsolla/xui-uploader';
import { Input } from '@xsolla/xui-input';
import { Textarea } from '@xsolla/xui-textarea';
import { Button } from '@xsolla/xui-button';

export default function FormWithUpload() {
  const [files, setFiles] = React.useState<File[]>([]);

  const handleSubmit = () => {
    const formData = new FormData();
    files.forEach((file) => formData.append('attachments', file));
    console.log('Submitting with', files.length, 'files');
  };

  return (
    <form
      style={{ display: 'flex', flexDirection: 'column', gap: 16, maxWidth: 400 }}
      onSubmit={(e) => { e.preventDefault(); handleSubmit(); }}
    >
      <Input label="Subject" placeholder="Enter subject" />
      <Textarea label="Message" placeholder="Enter your message" />
      <Uploader
        label="Attachments"
        placeholder="Add attachments"
        multiple
        onFilesChange={setFiles}
      />
      <Button type="submit">Submit</Button>
    </form>
  );
}

Different Sizes

import * as React from 'react';
import { Uploader } from '@xsolla/xui-uploader';

export default function UploaderSizes() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
      <Uploader size="xs" placeholder="Extra small" />
      <Uploader size="sm" placeholder="Small" />
      <Uploader size="md" placeholder="Medium" />
      <Uploader size="lg" placeholder="Large" />
      <Uploader size="xl" placeholder="Extra large" />
    </div>
  );
}

Disabled State

import * as React from 'react';
import { Uploader } from '@xsolla/xui-uploader';

export default function DisabledUploader() {
  return (
    <Uploader
      label="Upload (disabled)"
      placeholder="Cannot upload files"
      disabled
    />
  );
}

API Reference

Uploader

UploaderProps:

| Prop | Type | Default | Description | | :--- | :--- | :------ | :---------- | | label | string | - | Label text above the button. | | placeholder | string | "Select files to upload" | Button text. | | accept | string | - | Accepted file types (e.g., ".jpg,.png"). | | multiple | boolean | false | Allow multiple file selection. | | disabled | boolean | false | Disabled state. | | size | "xs" \| "sm" \| "md" \| "lg" \| "xl" | "md" | Button size. | | onFilesChange | (files: File[]) => void | - | Callback when files change. |

File List Display

When files are selected, they appear below the button with:

• File icon
• File name (truncated if too long)
• Remove button (X icon)

Removing a file updates the list and calls onFilesChange with the updated array.

Accept Patterns

| Pattern | Description | | :------ | :---------- | | .pdf | PDF files only | | .jpg,.jpeg,.png | Specific image formats | | image/* | All image types | | video/* | All video types | | .doc,.docx,.pdf | Multiple document types |

Behavior

• Click button to open native file picker
• Multiple selection when multiple is true
• Files accumulate when multiple is true (new selections add to existing)
• Files replace when multiple is false
• Each file can be removed individually
• Hidden native input, styled button

Accessibility

• Button is keyboard accessible
• File input is properly associated with the button
• Remove buttons have appropriate labels
• Disabled state prevents interaction
• File list is accessible to screen readers