Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsShowcaseBlogGuides
Sponsor

File Upload

Used to select and upload files from their device.

SourceStorybookRecipeArk
AI TipWant to skip the docs? Use the MCP Server

    Usage

    import { FileUpload } from "@chakra-ui/react"
    <FileUpload.Root>
  <FileUpload.HiddenInput />
  <FileUpload.Label />
  <FileUpload.Dropzone>
    <FileUpload.DropzoneContent />
  </FileUpload.Dropzone>
  <FileUpload.Trigger />
  <FileUpload.ItemGroup>
    <FileUpload.Item>
      <FileUpload.ItemPreview />
      <FileUpload.ItemFileName />
      <FileUpload.ItemSizeText />
      <FileUpload.ItemDeleteTrigger />
    </FileUpload.Item>
  </FileUpload.ItemGroup>
</FileUpload.Root>

    Shortcuts

    The FileUpload component also provides a set of shortcuts for common use cases.

    FileUploadItems

    By default, the FileUploadItems shortcut renders the list of uploaded files.

    This works:

    <FileUpload.ItemGroup>
  <FileUpload.Context>
    {({ acceptedFiles }) =>
      acceptedFiles.map((file) => (
        <FileUpload.Item key={file.name} file={file}>
          <FileUpload.ItemPreview />
          <FileUpload.ItemName />
          <FileUpload.ItemSizeText />
          <FileUpload.ItemDeleteTrigger />
        </FileUpload.Item>
      ))
    }
  </FileUpload.Context>
</FileUpload.ItemGroup>

    This might be more concise, if you don't need to customize the file upload items:

    <FileUpload.ItemGroup>
  <FileUpload.Items />
</FileUpload.ItemGroup>

    FileUploadList

    The FileUploadList shortcut renders the list of uploaded files. It composes the FileUpload.ItemGroup and FileUpload.Items components.

    <FileUpload.List />

    is the same as:

    <FileUpload.ItemGroup>
  <FileUpload.Items />
</FileUpload.ItemGroup>

    Examples

    Accepted Files

    Define the accepted files for upload using the accept prop.

      Multiple Files

      Upload multiple files at once by using the maxFiles prop.

        Custom Preview

        Here's an example of how to show a custom image preview for files.

        Directory

        Use the directory prop to allow selecting a directory instead of a file.

          Media Capture

          Use the capture prop to select and upload files from different environments and media types.

          Note: This is not fully supported in all browsers.

            Dropzone

            Drop multiple files inside the dropzone and use the maxFiles prop to set the number of files that can be uploaded at once.

            Drag and drop files here
            .png, .jpg up to 5MB

              Conditional Dropzone

              Hide the dropzone when the maximum number of files has been reached by using useFileUploadContext to access the accepted files count.

              Drag and drop files here
              3 more files allowed

                Input

                Use the FileInput component to create a trigger that looks like a text input.

                Clearable

                Here's an example of a clearable file upload input.

                Pasting Files

                Here's an example of handling files pasted from the clipboard.

                  Store

                  An alternative way to control the file upload is to use the RootProvider component and the useFileUpload store hook.

                  This way you can access the file upload state and methods from outside the file upload.

                  accepted: rejected:

                    Props

                    Root

                    PropDefaultType
                    allowDrop true
                    boolean

                    Whether to allow drag and drop in the dropzone element

                    locale en-US
                    string

                    The current locale. Based on the BCP 47 definition.

                    maxFiles 1
                    number

                    The maximum number of files

                    maxFileSize Infinity
                    number

                    The maximum file size in bytes

                    minFileSize 0
                    number

                    The minimum file size in bytes

                    preventDocumentDrop true
                    boolean

                    Whether to prevent the drop event on the document

                    as
                    React.ElementType

                    The underlying element to render.

                    asChild
                    boolean

                    Use the provided child element as the default rendered element, combining their props and behavior.

                    For more details, read our Composition guide.
                    unstyled
                    boolean

                    Whether to remove the component's style.

                    accept
                    Record<string, string[]> | FileMimeType | FileMimeType[]

                    The accept file types

                    acceptedFiles
                    File[]

                    The controlled accepted files

                    capture
                    'user' | 'environment'

                    The default camera to use when capturing media

                    defaultAcceptedFiles
                    File[]

                    The default accepted files when rendered. Use when you don't need to control the accepted files of the input.

                    directory
                    boolean

                    Whether to accept directories, only works in webkit browsers

                    disabled
                    boolean

                    Whether the file input is disabled

                    ids
                    Partial<{ root: string dropzone: string hiddenInput: string trigger: string label: string item: (id: string) => string itemName: (id: string) => string itemSizeText: (id: string) => string itemPreview: (id: string) => string }>

                    The ids of the elements. Useful for composition.

                    invalid
                    boolean

                    Whether the file input is invalid

                    name
                    string

                    The name of the underlying file input

                    onFileAccept
                    (details: FileAcceptDetails) => void

                    Function called when the file is accepted

                    onFileChange
                    (details: FileChangeDetails) => void

                    Function called when the value changes, whether accepted or rejected

                    onFileReject
                    (details: FileRejectDetails) => void

                    Function called when the file is rejected

                    required
                    boolean

                    Whether the file input is required

                    transformFiles
                    (files: File[]) => Promise<File[]>

                    Function to transform the accepted files to apply transformations

                    translations
                    IntlTranslations

                    The localized messages to use.

                    validate
                    (file: File, details: FileValidateDetails) => FileError[] | null

                    Function to validate a file

                    Explorer

                    Explore the File Upload component parts interactively. Click on parts in the sidebar to highlight them in the preview.

                    Let’s Add Some Naruto Images

                    You can upload up to 3 images by dragging them here or browsing.

                    Drag & drop files here

                    or click below to browse files

                    uzumaki_naruto.svg

                    Uploaded Files

                    • uzumaki_naruto.svg
                      256 byte

                    Component Anatomy

                    Hover to highlight, click to select parts

                    root

                    dropzone

                    item

                    itemDeleteTrigger

                    itemGroup

                    itemName

                    itemPreview

                    itemPreviewImage

                    itemSizeText

                    label

                    trigger

                    clearTrigger

                    itemContent

                    dropzoneContent

                    fileText

                    file-upload.recipe.ts

                    Previous

                    Fieldset

                    Next

                    Input