Storage Components | Sylphx Documentation

FileUpload

General file upload with drag-and-drop support

ImageUploader

Image-specific upload with preview and validation

AvatarUpload

Circular avatar upload with cropping support

Quick Start

All storage components are available from the SDK. Wrap your app with SylphxProvider for automatic storage context and authentication.

Installation

import {
  FileUpload,
  ImageUploader,
  AvatarUpload,
} from '@sylphx/platform-sdk/react'

FileUpload

A versatile file upload component with drag-and-drop support, progress tracking, and file type validation. Handles single or multiple file uploads with customizable restrictions.

Drag & Drop

Themeable

Type Validation

Basic Usage

import { FileUpload } from '@sylphx/platform-sdk/react'

export default function UploadPage() {
  return (
    <div className="max-w-xl mx-auto py-8">
      <FileUpload
        onUpload={(files) => {
          console.log('Uploaded files:', files)
        }}
        onError={(error) => {
          console.error('Upload failed:', error.message)
        }}
      />
    </div>
  )
}

Props

Property	Type	Description
`onUpload`required	`(files: UploadedFile[]) => void`	Callback fired after successful upload
`onError`	`(error: UploadError) => void`	Callback fired on upload error
`onProgress`	`(progress: number) => void`	Callback fired during upload with progress percentage
`accept`	`string \| string[]`= "/"	Accepted file types (MIME or extensions)
`maxSize`	`number`= 10485760	Maximum file size in bytes
`maxFiles`	`number`= 10	Maximum number of files for multi-upload
`multiple`	`boolean`= false	Allow multiple file selection
`path`	`string`= "uploads"	Storage path/folder for uploads
`public`	`boolean`= true	Make uploaded files publicly accessible
`showPreview`	`boolean`= true	Show file preview after selection
`showProgress`	`boolean`= true	Show upload progress bar
`disabled`	`boolean`= false	Disable the upload component
`placeholder`	`string`= "Drag & drop files here"	Placeholder text
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Advanced Examples

<FileUpload
  accept={['.pdf', '.doc', '.docx', '.txt']}
  maxSize={25 * 1024 * 1024} // 25MB
  path="documents"
  public={false}
  placeholder="Drop your documents here"
  onUpload={(files) => {
    files.forEach(file => {
      console.log('Uploaded:', file.filename, file.url)
    })
  }}
/>

File Type Validation

Use MIME types (image/*, application/pdf) or extensions (.pdf, .docx) in the accept prop. Arrays allow multiple types.

ImageUploader

An image-specific upload component with instant preview, dimension validation, and format conversion. Optimized for image handling with built-in compression options.

Preview

Auto Resize

Compression

Basic Usage

import { ImageUploader } from '@sylphx/platform-sdk/react'

export default function GalleryPage() {
  return (
    <div className="max-w-xl mx-auto py-8">
      <ImageUploader
        onUpload={(image) => {
          console.log('Uploaded image:', image.url)
          console.log('Dimensions:', image.width, 'x', image.height)
        }}
      />
    </div>
  )
}

Props

Property	Type	Description
`onUpload`required	`(image: UploadedImage) => void`	Callback fired after successful upload
`onError`	`(error: UploadError) => void`	Callback fired on upload error
`onPreview`	`(preview: string) => void`	Callback fired when preview is generated
`accept`	`string[]`= ["image/jpeg", "image/png", "image/webp", "image/gif"]	Accepted image types
`maxSize`	`number`= 10485760	Maximum file size in bytes
`maxWidth`	`number`	Maximum image width (auto-resize if exceeded)
`maxHeight`	`number`	Maximum image height (auto-resize if exceeded)
`minWidth`	`number`	Minimum required image width
`minHeight`	`number`	Minimum required image height
`aspectRatio`	`number`	Required aspect ratio (width/height)
`quality`	`number`= 85	Compression quality (0-100)
`format`	`"jpeg" \| "png" \| "webp"`	Output format (converts if different)
`path`	`string`= "images"	Storage path/folder
`public`	`boolean`= true	Make publicly accessible
`showPreview`	`boolean`= true	Show image preview
`previewSize`	`"sm" \| "md" \| "lg" \| "full"`= "md"	Preview size
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Advanced Examples

<ImageUploader
  minWidth={800}
  minHeight={800}
  maxWidth={2000}
  maxHeight={2000}
  aspectRatio={1} // Square images
  quality={90}
  format="webp"
  path="products"
  onUpload={(image) => {
    setProductImage(image.url)
    toast.success('Product image uploaded!')
  }}
  onError={(error) => {
    if (error.code === 'DIMENSION_TOO_SMALL') {
      toast.error('Image must be at least 800x800 pixels')
    }
  }}
/>

WebP Format

Using format="webp" typically reduces file size by 25-35% compared to JPEG while maintaining quality. All modern browsers support WebP.

AvatarUpload

A specialized avatar upload component with built-in circular cropping, zoom controls, and automatic resizing. Designed for profile pictures with an intuitive editing experience.

Circular Crop

Profile Ready

Zoom & Pan

Basic Usage

import { AvatarUpload } from '@sylphx/platform-sdk/react'

export default function ProfilePage() {
  const { user, refreshUser } = useUser()

  return (
    <div className="flex items-center gap-6">
      <AvatarUpload
        currentImage={user?.avatar}
        onUpload={async (avatar) => {
          await refreshUser()
          toast.success('Avatar updated!')
        }}
      />
      <div>
        <h2 className="text-xl font-semibold">{user?.name}</h2>
        <p className="text-muted-foreground">{user?.email}</p>
      </div>
    </div>
  )
}

Props

Property	Type	Description
`onUpload`required	`(avatar: UploadedImage) => void`	Callback fired after successful upload
`onError`	`(error: UploadError) => void`	Callback fired on upload error
`onRemove`	`() => void`	Callback fired when avatar is removed
`currentImage`	`string`	Current avatar URL to display
`size`	`number`= 120	Avatar size in pixels
`outputSize`	`number`= 256	Output image size in pixels
`accept`	`string[]`= ["image/jpeg", "image/png", "image/webp"]	Accepted image types
`maxSize`	`number`= 5242880	Maximum file size in bytes
`quality`	`number`= 90	Output quality (0-100)
`showCropper`	`boolean`= true	Show crop interface
`cropShape`	`"circle" \| "square"`= "circle"	Crop area shape
`allowZoom`	`boolean`= true	Allow zoom controls in cropper
`allowRemove`	`boolean`= true	Show remove avatar button
`fallback`	`ReactNode`	Fallback content when no image
`fallbackInitials`	`string`	Initials to show as fallback
`updateUserProfile`	`boolean`= true	Auto-update user profile
`theme`	`ThemeVariables`	Custom theme overrides
`className`	`string`	Additional CSS classes

Advanced Examples

<AvatarUpload
  currentImage={user?.avatar}
  fallbackInitials={user?.name?.split(' ').map(n => n[0]).join('')}
  size={100}
  outputSize={256}
  onUpload={(avatar) => {
    updateUser({ avatar: avatar.url })
  }}
  onRemove={() => {
    updateUser({ avatar: null })
  }}
/>

Automatic Profile Update

When updateUserProfile is enabled (default), the component automatically updates the current user's profile. Disable this for team member avatars or other non-user images.

Theming

All storage components support theming via the theme prop. Customize colors, borders, and spacing to match your brand.

Custom Theme

import { FileUpload, ImageUploader, AvatarUpload, defaultTheme, type ThemeVariables } from '@sylphx/platform-sdk/react'

const customTheme: ThemeVariables = {
  ...defaultTheme,
  colorPrimary: '#6366f1',
  colorPrimaryHover: '#4f46e5',
  colorBackground: '#ffffff',
  colorForeground: '#1f2937',
  colorMuted: '#f3f4f6',
  colorMutedForeground: '#6b7280',
  colorBorder: '#e5e7eb',
  colorSuccess: '#22c55e',
  colorDestructive: '#ef4444',
  fontFamily: 'Inter, sans-serif',
  borderRadius: '0.75rem',
}

<FileUpload theme={customTheme} />
<ImageUploader theme={customTheme} />
<AvatarUpload theme={customTheme} />

Property	Type	Description
`colorPrimary`	`string`= #000000	Primary/accent color
`colorPrimaryHover`	`string`= #1f2937	Primary color on hover
`colorBackground`	`string`= #ffffff	Component background
`colorForeground`	`string`= #1f2937	Primary text color
`colorMuted`	`string`= #f3f4f6	Muted/secondary background
`colorMutedForeground`	`string`= #6b7280	Secondary text color
`colorBorder`	`string`= #e5e7eb	Border color
`colorSuccess`	`string`= #22c55e	Success/complete color
`colorDestructive`	`string`= #ef4444	Error/remove color
`fontFamily`	`string`= system-ui	Font family
`borderRadius`	`string`= 0.5rem	Border radius

Best Practices

Validate File Types

Always specify accepted file types to prevent unwanted uploads and improve user experience.

Set Size Limits

Configure appropriate maxSize limits based on your use case and storage plan.

Handle Errors Gracefully

Provide onError callbacks with user-friendly messages for validation and upload failures.

Optimize Images

Use compression (quality prop) and format conversion (WebP) to reduce storage and bandwidth costs.

Need more control?

Use the storage hooks for custom upload UI while keeping all the processing and validation.

Storage API Access Control

File Uploads

Learn about the storage API and hooks

Access Control

Manage file permissions and signed URLs