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

maxSize · 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.

maxSelect · int · default: "1"

Maximum number of files allowed. Set to 1 (or less) for single file mode. Set to > 1 for multiple files mode.

mimeTypes · []string

Optional list of allowed file MIME types. Leave empty to allow all file types.

thumbs · []string

Optional list of image thumbnail sizes to generate. Each entry must be in a specific format (see Thumbnail formats section).

protected · bool · default: "false"

When true, requires users to provide a special file token to access the file. By default, all files are publicly accessible.

required · bool · default: "false"

When true, requires at least one file to be uploaded.

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:

Append files

// Add files to the end
record.Set("documents+", []*filesystem.File{new1, new2})
// Result: ["old1.txt", "old2.txt", "new1_ajkvass.txt", "new2_klhfnwd.txt"]

Go examples

Single file upload

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)

Multiple files

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)

Protected images

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)

Any file type

field := &core.FileField{
    Name:      "files",
    MaxSelect: 3,
    MaxSize:   20 << 20, // 20MB
    // No mimeTypes restriction
}

collection.Fields.Add(field)

Database column type

The column type varies based on single or multiple files:

Single file (maxSelect <= 1)

TEXT DEFAULT '' NOT NULL

File URLs

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

Public file URL

const url = `${pb.baseUrl}/api/files/${record.collectionName}/${record.id}/${filename}`;

Common MIME types

Images

MimeTypes: []string{
    "image/jpeg",
    "image/png",
    "image/gif",
    "image/webp",
    "image/svg+xml",
}

Special getter

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

// Get unsaved/uploaded files
unsavedFiles := record.Get("documents:unsaved").([]*filesystem.File)

File naming

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.

Best practices

• 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

Zero value

• Single file: Empty string ""
• Multiple files: Empty array []