Skip to content
Sanity Studio v3 is here. Find out more on our blog →

File

A file is a special kind of object 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).

Gotcha

You shouldn't use the file type for images. Use image 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

  • REQUIREDtypestring

    Required. Value must be set to file.

  • REQUIREDnamestring

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

  • fieldsarray

    An array of optional fields to add to the file field. The fields added here follow the same pattern as fields defined on objects. This is useful for allowing users to add custom metadata related to the usage of this file (see example below).

  • titlestring

    Human readable label for the field.

  • hiddenboolean | function

    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.

  • readOnlyboolean | function

    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.

  • descriptionstring

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

  • initialValueInitialValueOrResolverFunction

    The initial value used when creating new values from this type. Can be either a literal value or a resolver function that returns either a literal value or a promise resolving to the initial value.

  • componentesobject

    Lets you provide custom components to override the studio defaults in various contexts. The components available are field, input, item, preview.

Options

  • storeOriginalFilenameboolean

    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.

  • acceptstring

    This specifies which mime types the file input can accept. Just like the accept attribute on native DOM file inputs and you can specify any valid file type specifier: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#Unique_file_type_specifiers

  • sourcesarray

    Lock the asset sources available to this type to a specific subset. Import the plugins by their part name, and use the import variable name as array entries. The built in default asset source has the part name part:@sanity/form-builder/input/file/asset-source-default

    Read more about custom asset sources

Validation

Learn more about validation

Input

{
  title: 'Manuscript',
  name: 'manuscript',
  type: 'file',
  fields: [
    {
      name: 'description',
      type: 'string',
      title: 'Description'
    },
    {
      name: 'author',
      type: 'reference',
      title: 'Author',
      to: {type: 'person'}
    }
  ]
}

Output

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

Download file

In order to download a file from your front-end you need to append ?dl=<filename-of-your-choice.pdf> to the file URL. If you leave the filename blank, the original filename will be used if present. If the original filename is not available, the id of the file will be used instead. 

// GROQ query
*[_type == 'movie'] {
  title,
  "manuscriptURL": manuscript.asset->url
}

// Then you can use the URL in HTML for example like this:
// <a href={`${manuscriptURL}?dl=`}>Manuscript</a>

Updated on December 7, 2022

Was this article helpful?