---
title: FileInput
description: "`FileInput` is a component used for users to select files."
links:
  - style: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/file-input/file-input.style.ts
  - source: https://github.com/yamada-ui/yamada-ui/tree/main/packages/react/src/components/file-input
  - storybook: https://yamada-ui.github.io/yamada-ui?path=/story/components-fileinput--basic
---

```tsx
<FileInput placeholder="Please upload file" />
```

## Usage

```tsx
import { FileInput } from "@yamada-ui/react"
```

```tsx
import { FileInput } from "@/components/ui"
```

```tsx
import { FileInput } from "@workspaces/ui"
```

```tsx
<FileInput />
```

### Change Variant

```tsx
<VStack>
  <For each={["outline", "filled", "flushed"]}>
    {(variant, index) => (
      <FileInput
        key={index}
        variant={variant}
        placeholder={toTitleCase(variant)}
      />
    )}
  </For>
</VStack>
```

### Change Size

```tsx
<VStack>
  <For each={["xs", "sm", "md", "lg", "xl"]}>
    {(size, index) => (
      <FileInput key={index} size={size} placeholder={toTitleCase(size)} />
    )}
  </For>
</VStack>
```

### Change Color Scheme

```tsx
<VStack>
  <For each={["success", "warning"]}>
    {(colorScheme, index) => (
      <FileInput
        key={index}
        colorScheme={colorScheme}
        placeholder={toTitleCase(colorScheme)}
      />
    )}
  </For>
</VStack>
```

### Allow Multiple Selection

To allow multiple selection, set `multiple` to `true`.

```tsx
<FileInput placeholder="multiple" multiple />
```

### Specify File Extensions

To specify file extensions, set `accept` to a string(type).

```tsx
<FileInput accept="image/png,image/jpeg" placeholder="only png, jpeg" />
```

### Customize Separator

To customize the separator, set `separator` to a string.

```tsx
<FileInput placeholder="Please upload file" multiple separator=";" />
```

### Use Custom Component

To use a custom component, set `component` to a `ReactNode`. `component` provides `value`(`File`) and `index`.

```tsx
<FileInput
  component={({ value: { name } }) => <Tag>{name}</Tag>}
  gapY="xs"
  multiple
  placeholder="Please upload file"
/>
```

### Format File Names

To format file names, use `format`. `format` provides `File`.

```tsx
<FileInput
  format={({ name }) => name.substring(0, name.indexOf("."))}
  multiple
  placeholder="Please upload file"
/>
```

### Customize Children

To customize children, use `children`. `children` provides `File` as an array.

```tsx
<FileInput multiple>
  {(files) => <Text>Selected: {files?.length ?? 0}</Text>}
</FileInput>
```

### Add Addon

To add an addon, wrap `FileInput` with `InputGroup.Root` and use `InputGroup.Addon`.

```tsx
<InputGroup.Root>
  <InputGroup.Addon>
    <FileIcon />
  </InputGroup.Addon>
  <FileInput placeholder="Please upload file" />
</InputGroup.Root>
```

### Add Element

To add an element, wrap `FileInput` with `InputGroup.Root` and use `InputGroup.Element`.

```tsx
<InputGroup.Root>
  <InputGroup.Element>
    <FileIcon />
  </InputGroup.Element>
  <FileInput placeholder="Please upload file" />
</InputGroup.Root>
```

### Disable

To disable, set `disabled` to `true`.

```tsx
<VStack>
  <FileInput placeholder="Please upload file" disabled />

  <InputGroup.Root disabled>
    <InputGroup.Addon>
      <FileIcon />
    </InputGroup.Addon>
    <FileInput placeholder="Please upload file" />
  </InputGroup.Root>

  <Field.Root disabled label="Upload file">
    <FileInput placeholder="Please upload file" />
  </Field.Root>
</VStack>
```

### Read-Only

To make it read-only, set `readOnly` to `true`.

```tsx
<VStack>
  <FileInput placeholder="Please upload file" readOnly />

  <InputGroup.Root readOnly>
    <InputGroup.Addon>
      <FileIcon />
    </InputGroup.Addon>
    <FileInput placeholder="Please upload file" />
  </InputGroup.Root>

  <Field.Root readOnly label="Upload file">
    <FileInput placeholder="Please upload file" />
  </Field.Root>
</VStack>
```

### Invalid

To make the input invalid, set `invalid` to `true`.

```tsx
<VStack>
  <FileInput placeholder="Please upload file" invalid />

  <InputGroup.Root invalid>
    <InputGroup.Addon>
      <FileIcon />
    </InputGroup.Addon>
    <FileInput placeholder="Please upload file" />
  </InputGroup.Root>

  <Field.Root errorMessage="File is required." invalid label="Upload file">
    <FileInput placeholder="Please upload file" />
  </Field.Root>
</VStack>
```

### Change Border Color

To change the border color, set a color to `focusBorderColor` or `errorBorderColor`.

```tsx
<VStack>
  <FileInput
    focusBorderColor="success"
    placeholder="Custom focus border color"
  />

  <InputGroup.Root variant="flushed" focusBorderColor="success">
    <InputGroup.Element>
      <FileIcon />
    </InputGroup.Element>
    <FileInput placeholder="Custom focus border color" />
  </InputGroup.Root>

  <FileInput
    errorBorderColor="warning"
    invalid
    placeholder="Custom error border color"
  />

  <InputGroup.Root errorBorderColor="warning" invalid>
    <InputGroup.Addon>
      <FileIcon />
    </InputGroup.Addon>
    <FileInput placeholder="Custom error border color" />
  </InputGroup.Root>
</VStack>
```

### Reset

To reset the value, set `resetRef` to `ref`. A callback function will be attached to the set `ref`, execute it.

```tsx
const [value, onChange] = useState<File[] | undefined>(undefined)
const resetRef = useRef<() => void>(null)
const onReset = () => {
  onChange(undefined)
  resetRef.current?.()
}

return (
  <VStack>
    <Text>files: {value?.length ?? 0}</Text>

    <InputGroup.Root>
      <FileInput
        multiple
        placeholder="placeholder"
        resetRef={resetRef}
        value={value}
        onChange={onChange}
      />

      {value?.length ? (
        <InputGroup.Element clickable onClick={onReset}>
          <Center as="button" focusVisibleRing="outside" p="0.5" rounded="xs">
            <XIcon fontSize="xl" />
          </Center>
        </InputGroup.Element>
      ) : null}
    </InputGroup.Root>
  </VStack>
)
```

## Uses Components & Hooks

<Uses name="file-input" />

## Used By Components & Hooks

<UsedBy name="file-input" />

## Props

| Prop               | Default     | Type                                                                                                                                                                        | Description                                            |
| ------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `as`               | -           | `As`                                                                                                                                                                        | The HTML element to render.                            |
| `asChild`          | -           | `boolean`                                                                                                                                                                   | Merges its props onto its immediate child.             |
| `css`              | -           | `CSSObject \| CSSObject[]`                                                                                                                                                  | The CSS object.                                        |
| `colorScheme`      | -           | `"amber" \| "black" \| "blackAlpha" \| "blue" \| "cyan" \| "danger" \| "emerald" \| "error" \| "flashy" \| "fuchsia" ...`                                                   | Set color scheme variables.                            |
| `size`             | `"md"`      | `"2xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"`                                                                                                                             | The size of the component.                             |
| `variant`          | `"outline"` | `"filled" \| "flushed" \| "outline" \| "plain"`                                                                                                                             | The variant of the component.                          |
| `children`         | -           | `(files: File[] \| undefined) => ReactNode`                                                                                                                                 | A callback that returns a React node.                  |
| `component`        | -           | `(props: { index: number; value: File }) => ReactNode`                                                                                                                      | The component that displays uploaded files.            |
| `defaultValue`     | -           | `File[]`                                                                                                                                                                    | The initial value of the file input.                   |
| `errorBorderColor` | -           | `"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` | The border color when the input is invalid.            |
| `focusBorderColor` | -           | `"-moz-initial" \| "AccentColor" \| "AccentColorText" \| "ActiveBorder" \| "ActiveCaption" \| "ActiveText" \| "aliceblue" \| "amber.100" \| "amber.200" \| "amber.300" ...` | The border color when the input is focused.            |
| `format`           | -           | `(value: File, index: number) => string`                                                                                                                                    | A callback that formats the name of the uploaded file. |
| `invalid`          | `false`     | `boolean`                                                                                                                                                                   | If `true`, the field will be invalid.                  |
| `onChange`         | -           | `(files: File[] \| undefined) => void`                                                                                                                                      | Function to be called when a file change event occurs. |
| `resetRef`         | -           | `RefObject<(() => void) \| null>`                                                                                                                                           | Ref to a reset function.                               |
| `separator`        | `","`       | `string`                                                                                                                                                                    | The string to separate uploaded files.                 |
| `value`            | -           | `File[]`                                                                                                                                                                    | The value of the file input.                           |

## Accessibility

If you are not using `Field.Root`, set `aria-label` or `aria-labelledby` to `FileInput`.

```tsx
<FileInput aria-label="Upload file" placeholder="Please upload file" />
```

```tsx
<VStack gap="sm">
  <Text as="h3" id="label">
    Upload file
  </Text>

  <FileInput aria-labelledby="label" placeholder="Please upload file" />
</VStack>
```

### Keyboard Navigation

| Key              | Description                    | State |
| ---------------- | ------------------------------ | ----- |
| `Tab`            | Focuses the element.           | -     |
| `Space`, `Enter` | Activates the focused element. | -     |

### ARIA Roles and Attributes

| Component   | Roles and Attributes | Usage                                                                                                                                                           |
| ----------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FileInput` | `role="button"`      | Indicates that this is a button.                                                                                                                                |
|             | `aria-disabled`      | Sets to `"true"` if `disabled` or `readOnly` is set.                                                                                                            |
|             | `aria-labelledby`    | If `FileInput` is within a `Field.Root` and `Field.Root` has a `label`, sets its `id`.                                                                          |
|             | `aria-describedby`   | If `FileInput` is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, `Field.ErrorMessage`, or `Field.HelperMessage`, sets its `id`. |
|             | `aria-invalid`       | Sets to `"true"` if `invalid` is set.                                                                                                                           |
|             | `aria-required`      | Sets to `"true"` if `required` is set.                                                                                                                          |
| `input`     | `aria-disabled`      | Sets to `"true"` if `disabled` or `readOnly` is set.                                                                                                            |
|             | `aria-describedby`   | If `FileInput` is within a `Field.Root` and `Field.Root` has an `errorMessage`, `helperMessage`, `Field.ErrorMessage`, or `Field.HelperMessage`, sets its `id`. |
|             | `aria-hidden`        | Excludes the element from the accessibility tree.                                                                                                               |
|             | `aria-invalid`       | Sets to `"true"` if `invalid` is set.                                                                                                                           |
|             | `aria-required`      | Sets to `"true"` if `required` is set.                                                                                                                          |