> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pocketbase/pocketbase/llms.txt
> Use this file to discover all available pages before exploring further.

# File field

> Upload and manage files with validation, thumbnails, and protection options

The file field manages file uploads and stores file names as record values. It supports single or multiple files, automatic thumbnail generation for images, MIME type validation, and file protection.

## Configuration options

<ParamField path="maxSize" type="int64" default="5242880">
  Maximum size of a single uploaded file in bytes (up to 2^53-1). Defaults to 5MB if not set or zero.
</ParamField>

<ParamField path="maxSelect" type="int" default="1">
  Maximum number of files allowed. Set to 1 (or less) for single file mode. Set to > 1 for multiple files mode.
</ParamField>

<ParamField path="mimeTypes" type="[]string">
  Optional list of allowed file MIME types. Leave empty to allow all file types.
</ParamField>

<ParamField path="thumbs" type="[]string">
  Optional list of image thumbnail sizes to generate. Each entry must be in a specific format (see Thumbnail formats section).
</ParamField>

<ParamField path="protected" type="bool" default="false">
  When true, requires users to provide a special file token to access the file. By default, all files are publicly accessible.
</ParamField>

<ParamField path="required" type="bool" default="false">
  When true, requires at least one file to be uploaded.
</ParamField>

## Thumbnail formats

For image files, you can specify thumbnails in these formats:

* `WxH` (e.g., `100x300`) - Crop to WxH viewbox from center
* `WxHt` (e.g., `100x300t`) - Crop to WxH viewbox from top
* `WxHb` (e.g., `100x300b`) - Crop to WxH viewbox from bottom
* `WxHf` (e.g., `100x300f`) - Fit inside WxH viewbox without cropping
* `0xH` (e.g., `0x300`) - Resize to H height preserving aspect ratio
* `Wx0` (e.g., `100x0`) - Resize to W width preserving aspect ratio

## Validation rules

The file field validates:

* **File count**: Number of files cannot exceed `maxSelect`
* **File size**: Each file must be under `maxSize` bytes
* **MIME type**: If `mimeTypes` is set, files must match one of the allowed types
* **Filename**: Must be 1-150 characters and contain valid characters
* **Required**: If enabled, at least one file must be uploaded

## Special setter modifiers

The file field supports modifiers for manipulating files:

<CodeGroup>
  ```go Append files theme={null}
  // Add files to the end
  record.Set("documents+", []*filesystem.File{new1, new2})
  // Result: ["old1.txt", "old2.txt", "new1_ajkvass.txt", "new2_klhfnwd.txt"]
  ```

  ```go Prepend files theme={null}
  // Add files to the beginning
  record.Set("+documents", []*filesystem.File{new1, new2})
  // Result: ["new1_ajkvass.txt", "new2_klhfnwd.txt", "old1.txt", "old2.txt"]
  ```

  ```go Remove files theme={null}
  // Remove specific files
  record.Set("documents-", "old1.txt")
  // Result: ["old2.txt"]
  ```
</CodeGroup>

## Go examples

<Tabs>
  <Tab title="Single file upload">
    ```go theme={null}
    import "github.com/pocketbase/pocketbase/core"

    field := &core.FileField{
        Name:      "avatar",
        Required:  false,
        MaxSelect: 1,
        MaxSize:   5 << 20, // 5MB
        MimeTypes: []string{"image/jpeg", "image/png", "image/webp"},
        Thumbs:    []string{"100x100", "500x500f"},
    }

    collection.Fields.Add(field)
    ```
  </Tab>

  <Tab title="Multiple files">
    ```go theme={null}
    field := &core.FileField{
        Name:      "attachments",
        Required:  false,
        MaxSelect: 5,
        MaxSize:   10 << 20, // 10MB per file
        MimeTypes: []string{
            "application/pdf",
            "application/msword",
            "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
        },
    }

    collection.Fields.Add(field)
    ```
  </Tab>

  <Tab title="Protected images">
    ```go theme={null}
    field := &core.FileField{
        Name:      "privatePhotos",
        Required:  false,
        MaxSelect: 10,
        MaxSize:   8 << 20,
        MimeTypes: []string{"image/jpeg", "image/png"},
        Thumbs:    []string{"200x200", "800x600f"},
        Protected: true, // Requires file token to access
    }

    collection.Fields.Add(field)
    ```
  </Tab>

  <Tab title="Any file type">
    ```go theme={null}
    field := &core.FileField{
        Name:      "files",
        MaxSelect: 3,
        MaxSize:   20 << 20, // 20MB
        // No mimeTypes restriction
    }

    collection.Fields.Add(field)
    ```
  </Tab>
</Tabs>

## Database column type

The column type varies based on single or multiple files:

<CodeGroup>
  ```sql Single file (maxSelect <= 1) theme={null}
  TEXT DEFAULT '' NOT NULL
  ```

  ```sql Multiple files (maxSelect > 1) theme={null}
  JSON DEFAULT '[]' NOT NULL
  ```
</CodeGroup>

## File URLs

To access uploaded files, construct URLs using the following pattern:

<CodeGroup>
  ```javascript Public file URL theme={null}
  const url = `${pb.baseUrl}/api/files/${record.collectionName}/${record.id}/${filename}`;
  ```

  ```javascript Thumbnail URL theme={null}
  const thumbUrl = `${pb.baseUrl}/api/files/${record.collectionName}/${record.id}/${filename}?thumb=100x100`;
  ```

  ```javascript Protected file URL (requires token) theme={null}
  const token = await pb.files.getToken();
  const url = `${pb.baseUrl}/api/files/${record.collectionName}/${record.id}/${filename}?token=${token}`;
  ```
</CodeGroup>

## Common MIME types

<CodeGroup>
  ```go Images theme={null}
  MimeTypes: []string{
      "image/jpeg",
      "image/png",
      "image/gif",
      "image/webp",
      "image/svg+xml",
  }
  ```

  ```go Documents theme={null}
  MimeTypes: []string{
      "application/pdf",
      "application/msword",
      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "application/vnd.ms-excel",
      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  }
  ```

  ```go Videos theme={null}
  MimeTypes: []string{
      "video/mp4",
      "video/mpeg",
      "video/quicktime",
      "video/x-msvideo",
      "video/webm",
  }
  ```

  ```go Audio theme={null}
  MimeTypes: []string{
      "audio/mpeg",
      "audio/wav",
      "audio/ogg",
      "audio/webm",
  }
  ```
</CodeGroup>

## Special getter

The file field provides a special getter to access unsaved files:

```go theme={null}
// Get unsaved/uploaded files
unsavedFiles := record.Get("documents:unsaved").([]*filesystem.File)
```

## File naming

<Info>
  Uploaded files automatically get a random suffix appended to their names to ensure uniqueness and prevent collisions. For example, `document.pdf` becomes `document_x7k2m9p4.pdf`.
</Info>

## Best practices

<Note>
  * Set appropriate `maxSize` limits based on your use case and storage capacity
  * Use `mimeTypes` to restrict file types and improve security
  * Generate thumbnails for image galleries to improve performance
  * Use `protected: true` for sensitive files that require authentication
  * Consider the total storage size when setting `maxSelect` and `maxSize`
  * Clean up old files when records are deleted (handled automatically by PocketBase)
  * The maximum body size for requests is calculated from `maxSize * maxSelect`
</Note>

## Zero value

* **Single file**: Empty string `""`
* **Multiple files**: Empty array `[]`