---
id: api/commands/selectfile
title: selectFile | Cypress Documentation
description: >-
  Select a file or files in an HTML5 input element or simulate dragging a file
  or files into the browser in Cypress.
section: api
source_path: docs/api/commands/selectfile.mdx
version: a8fd16711bdda4c7b5645b9717e588ae99ec2470
updated_at: '2026-05-18T17:21:32.047Z'
---
# selectFile

Selects a file or files in an HTML5 input element or simulates dragging a file or files into the browser.

It is [unsafe](/llm/markdown/app/core-concepts/retry-ability.md#Only-queries-are-retried) to chain further commands that rely on the subject after `.selectFile()`.

## Syntax

```
.selectFile(file).selectFile(file, options).selectFile([file1, file2, ...]).selectFile([file1, file2, ...], options)
```

### Usage

**Correct Usage**

```
cy.get('input[type=file]').selectFile('file.json')cy.get('input[type=file]').selectFile(['file.json', 'file2.json'])cy.get('input[type=file]').selectFile({  contents: Cypress.Buffer.from('file contents'),  fileName: 'file.txt',  mimeType: 'text/plain',  lastModified: Date.now(),})cy.get('input[type=file]').selectFile('file.json', { action: 'drag-drop' })cy.document().selectFile('file.json', { action: 'drag-drop' })
```

**Incorrect Usage**

```
// Errors, cannot be chained off 'cy'cy.selectFile('file.json')// Will attempt to find a file called 'file contents'// on disk, probably not what you intendedcy.get('input[type=file]').selectFile('file contents')
```

### Arguments

**file _(String, Array, Object or Cypress.Buffer)_**

Either a single file, or an array of files. A file can be:

*   A path to a file within the project root (the directory that contains the default Cypress configuration file). Eg: `'path/to/file.json'`
*   `@alias` - An alias of any type, previously stored using `.as()`. Eg: `'@alias'`
*   A [`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) containing binary data, such as `Uint8Array.from('123')`. [`Cypress.Buffer`](/llm/markdown/api/utilities/buffer.md) instances, such as those returned by `cy.readFile('file.json', null)` or created by `Cypress.Buffer.from('foo')` are `TypedArray` instances.
*   An object with a non-null `contents` property, specifying details about the file. Eg: `{contents: '@alias', fileName: 'file.json'}`

If an object is provided, it can have the following properties.

| Option | Description |
| --- | --- |
| `contents` | The contents of the file. This can be a string shorthand as described above, a `TypedArray` instance containing binary data (such as a `Cypress.Buffer` instance) or a non-TypedArray object, which will be converted into a string with `JSON.stringify()` and `utf8` encoded. |
| `fileName` | The name of the file. If `contents` is a path on disk or an alias from `cy.readFile()` or `cy.fixture()`, this defaults to the actual filename. In any other case, this defaults to an empty string. |
| `mimeType` | The [mimeType](https://developer.mozilla.org/en-US/docs/Web/API/File/type) of the file. If omitted, it will be [inferred](https://github.com/jshttp/mime-types#mimelookuppath) from the file extension. If one cannot be inferred, it will default to an empty string. |
| `lastModified` | The file's last modified timestamp, in milliseconds elapsed since the UNIX epoch (eg. [`Date.prototype.getTime()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/getTime)). This defaults to `Date.now()`. |

**options _(Object)_**

Pass in an options object to change the default behavior of `.selectFile()`.

| Option | Default | Description |
| --- | --- | --- |
| `action` | `'select'` | Switches modes. Valid values are `select` and `drag-drop`. See [Action](#Action) below for more details. |
| `animationDistanceThreshold` | [`animationDistanceThreshold`](/llm/markdown/app/references/configuration.md#Actionability) | The distance in pixels an element must exceed over time to be [considered animating](/llm/markdown/app/core-concepts/interacting-with-elements.md#Animations). |
| `force` | `false` | Forces the action, disables [waiting for actionability](#Assertions). |
| `log` | `true` | Displays the command in the [Command log](/llm/markdown/app/core-concepts/open-mode.md#Command-Log). |
| `timeout` | [`defaultCommandTimeout`](/llm/markdown/app/references/configuration.md#Timeouts) | Time to wait for `.selectFile()` to resolve before [timing out](#Timeouts). |
| `waitForAnimations` | [`waitForAnimations`](/llm/markdown/app/references/configuration.md#Actionability) | Whether to wait for elements to [finish animating](/llm/markdown/app/core-concepts/interacting-with-elements.md#Animations) before executing the command. |

### Yields [Learn about subject management](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management)

*   `.selectFile()` yields the same subject it was given.
*   It is [unsafe](/llm/markdown/app/core-concepts/retry-ability.md#Only-queries-are-retried) to chain further commands that rely on the subject after `.selectFile()`.

### Action

Depending on the `action` set in the `options` argument, `.selectFile()` can simulate two different user behaviors:

#### `select` (default)

By default, `.selectFile()` runs in 'select' mode, mimicking a user selecting one or more files on an HTML5 input element. In this mode, the [subject](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Subject-Management) must be a single `input` element with `type="file"`, or a `label` element connected to an input (either with its `for` attribute or by containing the input).

#### `drag-drop`

Setting the action to `drag-drop` changes the behavior of the command to instead mimic a user dragging files from the operating system into the browser, and dropping them over the selected subject. In this mode, the subject can be any DOM element or the `document` as a whole.

## Examples

### From a file on disk

```
cy.get('input[type=file]').selectFile('path/to/file.json')cy.get('input[type=file]').selectFile('path/to/file.png')
```

If given a path, `.selectFile()` will search for the file relative to the project root and attach the file exactly as it exists on disk. This is the preferred way to work with files on disk, avoiding many encoding-related pitfalls.

### On a hidden input

```
cy.get('input[type=file]').selectFile('file.json', { force: true })
```

In many cases in modern applications, the underlying file input is hidden from view, and activated by a user clicking on a button. In these cases, you will need to tell Cypress to ignore its actionability checks and select the file even though a user would not be able to directly activate the file input.

### From a fixture

```
cy.fixture('file.json', null).as('myFixture')cy.get('input[type=file]').selectFile('@myFixture')
```

Note the use of `null` encoding. By default, `cy.fixture()` and `cy.readFile()` attempt to interpret files read from disk, which would result in a JSON file being decoded and re-encoded as a utf-8 string - the contents would be preserved, but formatting would not be and the encoding might change. See [`cy.fixture`](/llm/markdown/api/commands/fixture.md) or [`cy.readFile`](/llm/markdown/api/commands/readfile.md) for more details on file encoding.

### From an API response

```
cy.request('http://localhost:8888/users/827').its('body').as('responseBody')cy.get('input[type=file]').selectFile('@responseBody')
```

### Processing data inside the test

```
cy.readFile('users.json')  .then((users) => {    users[0].username = 'JohnCena'  })  .as('myFile')cy.get('input[type=file]').selectFile('@myFile')
```

### Selecting multiple files

```
cy.get('input[type=file]').selectFile([  'file1.json',  'file2.json',  'file3.json',])
```

This will fail unless the file input has the `multiple` property.

### Custom fileName, mimeType and lastModified

```
cy.get('input[type=file][multiple]')  .selectFile([    {      contents: 'cypress/fixtures/example.json',    },    {      contents: 'cypress/fixtures/example.json',      fileName: 'file.png',    },    {      contents: 'cypress/fixtures/example.json',      fileName: 'file.png',      mimeType: 'text/plain',      lastModified: new Date('Feb 18 1989').valueOf(),    },  ])  .then(($input) => {    const files = $input[0].files    // If nothing is specified, the fileName and MIME type will be inferred from the path on disk.:    expect(files[0].name).to.eq('example.json')    expect(files[0].type).to.eq('application/json')    // If the fileName is given, the MIME type will be inferred based on that.    expect(files[1].name).to.eq('file.png')    expect(files[1].type).to.eq('image/png')    // But an explicitly specified MIME type is always used.    expect(files[2].name).to.eq('file.png')    expect(files[2].type).to.eq('text/plain')    // lastModified defaults to the current time, but can be overridden.    expect(files[0].lastModified).to.be.closeTo(Date.now(), 1000)    expect(files[1].lastModified).to.be.closeTo(Date.now(), 1000)    expect(files[2].lastModified).to.eql(new Date('Feb 18 1989').valueOf())  })
```

### Dropping a file on the document

```
cy.document().selectFile('file.json', { action: 'drag-drop' })
```

## Notes

### Existence

#### Default file existence assertion

Whenever resolving a file path, `.selectFile()` asserts that the file exists and will fail if it does not exist. It will retry reading the file if it does not initially exist until the file exists or the command times out.

```
// will fail after the defaultCommandTimeout is reachedcy.get('input[type=file]').selectFile('does-not-exist.yaml')
```

### Actionability

#### The element must first reach actionability

`.selectFile()` is an "action command" that follows all the rules of [Actionability](/llm/markdown/app/core-concepts/interacting-with-elements.md).

## Rules

### Requirements [Learn about chaining commands](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Chains-of-Commands)

*   `.selectFile()` requires being chained off a command that yields DOM element(s). With the `input` action (default), it further requires a single `input` element with `type="file"`, or a `label` element attached to one.
*   If given a path, `.selectFile()` requires the file must exist.
*   If given an alias, `.selectFile()` requires that the subject of the alias must not be `null` or `undefined`.

### Assertions [Learn about assertions](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Assertions)

*   `.selectFile()` will automatically wait for the element to reach an [actionable state](/llm/markdown/app/core-concepts/interacting-with-elements.md).

### Timeouts [Learn about timeouts](/llm/markdown/app/core-concepts/introduction-to-cypress.md#Timeouts)

*   `.selectFile()` can time out waiting for the element to reach an [actionable state](/llm/markdown/app/core-concepts/interacting-with-elements.md).
*   `.selectFile()` can time out waiting for a file to exist on disk or for an alias to resolve.

## Command Log

**_Select file for input_**

```
cy.get('.file-input').selectFile(Cypress.Buffer.from('Hello world'))
```

The commands above will display in the Command Log as:

When clicking on `selectFile` within the command log, the console outputs the following:

## History

| Version | Changes |
| --- | --- |
| [9.4.0](/llm/markdown/app/references/changelog.md#9-4-0) | Support for `TypedArray` and `mimeType` property added. Default `fileName` name is no longer lost when working with aliases. |
| [9.3.0](/llm/markdown/app/references/changelog.md#9-3-0) | `.selectFile()` command added |

### Community Recognition

The `.selectFile()` command draws heavy inspiration from the now-deprecated Cypress File Upload plugin. It was made possible by [@abramenal](https://github.com/abramenal) and contributors to the [cypress-file-upload](https://github.com/abramenal/cypress-file-upload#contributors) repository.

## See also

*   [Guide: Variables and Aliases](/llm/markdown/app/core-concepts/variables-and-aliases.md)
*   [`.fixture()`](/llm/markdown/api/commands/fixture.md)
*   [`.get()`](/llm/markdown/api/commands/get.md)
*   [`.readFile()`](/llm/markdown/api/commands/readfile.md)