> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# File

Schema type reference for the File type.

A `file` is a special kind of [object](https://www.sanity.io/docs/studio/object-type) that includes an implicit asset field, which is a reference to a file asset document. This is useful for storing any kind of non-image files (pdf, mpeg, docx etc). See the [FileDefinition](https://reference.sanity.io/sanity/index/FileDefinition/) reference for the full type definition.

> [!WARNING]
> Gotcha
> You shouldn't use the `file` type for images. Use [image](https://www.sanity.io/docs/studio/image-type) instead. Images uploaded as files will not have the associated metadata for images and you won't be able to scale and crop them in the image pipeline.

## Properties

#### Properties

**type** (required)

Required. Value must be set to file.

**name** (required)

Required. The field name. This will be the key in the data record.

**fields**

An array of optional fields to add to the file field. These follow the same pattern as fields defined on objects, and are useful for custom metadata about how this file is used, such as a description or a credit. The Manuscript example below shows two.

**title**

Human readable label for the field.

**hidden**

If set to true, this field will be hidden in the studio. You can also return a callback function to use it as a conditional field.

**readOnly**

If set to true, this field will not be editable in the content studio. You can also return a callback function to use it as a conditional field.

**description**

Short description to editors how the field is to be used.

**initialValue**

The initial value used when creating new values of this type. Can be a literal value, or a resolver function that returns a literal value or a promise that resolves to one.

**components**

Lets you provide custom components to override the studio defaults in various contexts. The available keys are annotation, block, diff, field, inlineBlock, input, item, and preview.

**deprecated**

Marks a field or document type as deprecated in the studio interface and displays a user-defined message defined by the single required reason property.

If you deploy a GraphQL API schema, this property will translated into the @deprecated directive.

**icon**

Supply a custom icon for this field. See icons documentation for more information.

**fieldsets**

Groups fields together in the studio interface. Each fieldset has a `name`, `title`, and optional `options` for collapsing behavior.

**preview**

Configures how the document or object is previewed in lists and references. Accepts `select` and `prepare` properties.

**renderMembers**

Callback that customizes the members of this field's input. It receives the resolved member array and returns a member array, which lets you add decoration members between fields instead of defining empty placeholder fields.

Currently in beta and not part of the stable API.

## Options ([FileOptions](https://reference.sanity.io/sanity/index/FileOptions/))

#### Properties

**storeOriginalFilename**

This will store the original filename in the asset document. Please be aware that the name of uploaded files could reveal potentially sensitive information (e.g. top_secret_planned_featureX.pdf). Default is true.

**accept**

This specifies which mime types the file input can accept. It functions just like the accept attribute on native DOM file inputs and you can specify any valid file type specifier.

It is recommended to use MIME types ("application/pdf") over file extensions (".pdf") in order for hover notifications to work for drag and drop as browsers do not send the file name while hovering.

**sources**

Limits the asset sources available to this field to a specific subset. Takes an array of AssetSource objects: import the source from its plugin and list it here. Read more about custom asset sources.

**disableNew**

If set to true, hides the upload UI so that only existing assets can be selected. Useful for centralized asset management workflows where ad-hoc uploads should be prevented.

**collapsible**

If set to `true`, the field can be collapsed.

**collapsed**

If set to `true`, the field will be collapsed by default.

**columns**

Number of columns to use for the field layout.

**modal**

Controls how the modal (dialog for content editing) is rendered.

**mediaLibrary**

Configures Media Library asset selection for this field. Takes a MediaLibraryOptions object, not a boolean: {filters: [{name, query}]}, where each filter limits which Media Library assets can be selected.

Setting this option does not by itself enable the Media Library.

## Validation ([FileRule](https://reference.sanity.io/sanity/index/FileRule/))

#### Properties

**required()**

Ensures that this field exists.

**assetRequired()**

Like required but more specific. Requires that an actual asset is referenced to validate. Must be used together with required, i.e.: 
validation: (Rule) => Rule.required().assetRequired(),

**custom(fn)**

Creates a custom validation rule.

**error(message)**

Sets a custom error message for the preceding validation rule.

**warning(message)**

Sets a custom warning message for the preceding validation rule. Warnings do not prevent publishing.

**info(message)**

Sets a custom info message for the preceding validation rule. Info messages are purely informational and do not prevent publishing.

**valueOfField(path)**

Gets the value of a sibling field to use in validation. Useful for creating validation rules that depend on the value of another field.

**skip()**

Discards the validation rules set before it in the chain and makes the field optional. Rules chained after it still apply.

Input

```javascript
import {defineField, defineType} from 'sanity'

export const manuscriptType = defineType({
  title: 'Manuscript',
  name: 'manuscript',
  type: 'file',
  fields: [
    defineField({
      name: 'description',
      type: 'string',
      title: 'Description',
    }),
    defineField({
      name: 'author',
      type: 'reference',
      title: 'Author',
      to: [{type: 'person'}],
    }),
  ],
})
```

Response

```json
{
  "_type": "file",
  "asset": {
    "_type": "reference",
    "_ref": "file-5igDD9UuXffIucwZpyVthr0c"
  },
  "description": "First draft",
  "author": {
    "_type": "reference",
    "_ref": "1osKfX-49GLPg-2EeuOe-3ufEFE"
  }
}
```

## Download file

To download a file from your front end, append `?dl=<filename-of-your-choice.pdf>` to the file URL. If you leave the filename blank, the original filename is used when present; if it is not available, the id of the file is used instead.

This example assumes a `book` document type with a `manuscript` field of type `file`:

```groq
*[_type == "book" && defined(manuscript.asset)][0...10]{
  title,
  "manuscriptUrl": manuscript.asset->url
}
```

Then use the URL in your front end:

```jsx
<a href={`${manuscriptUrl}?dl=`}>Manuscript</a>
```

## Upload files by drag and drop or paste

When you drop or paste a file into the Portable Text editor or an array field, the Studio resolves one target member by asset kind, in a fixed order: the first `image` member, then the first `file` member, then the first `sanity.video` member. It then checks that one member against its `accept` option.

If that member does not accept the dropped file, the drop is rejected. The Studio does not fall through to other members of the same kind, so two `file` fields in one array with different `accept` values will not route files between them: only the first is ever considered.

Restricting a single file field to PDFs:

```javascript
import {defineField} from 'sanity'

defineField({
  name: 'pdfFile',
  type: 'file',
  options: {
    accept: 'application/pdf',
  },
})
```



## Related changelog entries

Entries are listed newest first; each link points to the full entry as markdown. Follow one when you need to know what changed, when, or why — for example, to summarize recent updates, explain behavior that differs from older documentation, or check whether a fix has shipped.

- [Sanity Studio v3.41.0: Sanity Studio Update: Enhanced Portable Text Editor, Bugfixes, and Automatic Key Creation for PTE Children](https://www.sanity.io/docs/changelog/9242c2ae-9089-42c5-a224-c14bc84021fd.md) — May 14, 2024
- [Sanity Studio v3.26.0: Deprecation Support for Documents and Fields, Comment Reactions ++](https://www.sanity.io/docs/changelog/5a99e214-6088-4d10-a0b7-14ca7c555c01.md) — January 23, 2024
- [Sanity Studio v3.21.0: Improvements and bugfixes](https://www.sanity.io/docs/changelog/db4600a6-be05-4116-bb32-273e1ecaabec.md) — December 5, 2023
- [Sanity Studio v2.17.0: Conditional Fields](https://www.sanity.io/docs/changelog/10aba481-ece9-4b41-b0e2-6b8e75e375c9.md) — August 26, 2021