Studio

File

Schema type reference for the File type.

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). See the FileDefinition reference for the full type definition.

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

  • Requiredtype

    Required. Value must be set to file.

  • Requiredname

    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)

  • 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)

  • 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

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

{
  "_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:

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

Then use the URL in your front end:

<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:

import {defineField} from 'sanity'

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

Document

Next

Geopoint

Was this page helpful?