Keystone Documentation

Appearance

File Upload ​

Allow customers to upload files such as images, documents, or designs for product customization.

Overview ​

File Upload is an input option type that enables customers to upload files from their device. It's ideal for collecting artwork, logos, designs, documents, or any files needed for custom products or orders.

Use File Upload for:

  • Custom artwork or designs
  • Logos for printing or engraving
  • Product images or references
  • Documents or specifications
  • Photos for personalization

Key characteristics:

  • Single file upload per option
  • Can be marked as required
  • Supports multiple file types
  • File size limits apply
  • Validates file before checkout
  • "Choose File" button interface

Configuration ​

Basic Settings ​

SettingDescription
LabelOption name displayed to customers (e.g., "Upload Your Logo")
Option is required for this option setIf enabled, customers must upload a file before adding to cart
Hide Label from storefrontIf enabled, only the file upload button is shown (label is hidden)

Advanced Settings ​

SettingDescription
Internal LabelAdmin-only identifier (replaces label in options list)
Help TextAdditional guidance shown to customers (based on display mode)

How to Add File Upload ​

  1. Navigate to Option Sets and open your option set
  2. Click Add Option
  3. Select File Upload from the Option Type modal
  4. Enter a Label (e.g., "Upload Your Design")
  5. Check Option is required if file upload is mandatory
  6. (Optional) Click Advanced Settings to add Internal Label or Help Text
  7. Click Save in the contextual save bar

Use Cases ​

Custom Logo Upload ​

Label: Upload Your Logo Required: Yes Help Text: Accepted formats: JPG, PNG, SVG. Minimum 300 DPI for best quality.

Result: Required file upload for customers to provide their logo for printing

Design Artwork ​

Label: Upload Design Artwork Required: Yes Help Text: High-resolution images (min 1200x1200px) work best. We accept JPG, PNG, PDF.

Result: Required upload for custom design artwork with quality guidelines

Reference Photo ​

Label: Upload Reference Photo Required: No Help Text: Optional: Upload a photo of what you'd like us to create

Result: Optional file upload for customers to provide reference images

Document Upload ​

Label: Upload Specifications Required: No Internal Label: Customer Spec Document Help Text: Upload PDF or Word document with your requirements

Result: Optional document upload for detailed specifications

Product Photo ​

Label: Upload Product Image Required: Yes Help Text: Clear photo showing the area you'd like customized

Result: Required photo upload for customization placement reference

File Requirements ​

Accepted File Types ​

Typically supported file formats include:

  • Images: JPG, JPEG, PNG, GIF, SVG, WEBP
  • Documents: PDF
  • Design Files: May vary by configuration

Check Your Settings

Contact support or check your app settings to confirm which file types are enabled for your store.

File Size Limits ​

  • Maximum file size limits are configured in your app settings
  • Typical limits range from 5MB to 50MB per file
  • Large files may take longer to upload
  • Customers see upload progress during file selection

File Storage ​

  • Uploaded files are securely stored
  • Files are attached to the order
  • Accessible from order details in Shopify admin
  • Files remain available for order fulfillment

Customer Experience ​

Upload interface:

  1. Customer clicks Choose File button
  2. Device file picker opens
  3. Customer selects file from their device
  4. File name appears next to button ("filename.jpg")
  5. Customer can change file by clicking Choose File again

Before adding to cart:

  • Required uploads must be completed
  • Invalid file types are rejected
  • File size validation occurs on upload
  • Error messages guide corrections

Styling ​

File Upload buttons inherit styling from your theme and customization settings:

Best Practices ​

Provide clear guidance:

  • Use Help Text to specify file requirements
  • List accepted file types
  • Mention size or resolution requirements
  • Explain what the file will be used for

Set appropriate requirements:

  • Mark as required only when file is essential
  • Consider making optional for reference uploads
  • Test the upload flow from customer perspective
  • Ensure error messages are helpful

Communicate file specifications:

  • Specify minimum resolution for print quality
  • Mention file size limits if restrictive
  • List preferred file formats
  • Provide examples of good uploads

Consider upload context:

  • Place upload option near related settings
  • Use Descriptive Text to provide instructions
  • Link to file preparation guides if needed
  • Offer support for file-related questions

Handle file quality:

  • Request high-resolution files for printing
  • Explain DPI requirements (e.g., 300 DPI)
  • Mention color mode if relevant (RGB vs CMYK)
  • Provide file preparation tips

Test on mobile devices:

  • File uploads work on mobile browsers
  • Camera roll access on smartphones
  • Test upload flow on various devices
  • Ensure button is easily tappable

Troubleshooting ​

Upload button not appearing: Check that File Upload option type is selected and saved

File rejected: Verify file type is supported and within size limits

Upload fails: Check internet connection, try smaller file, or different format

File not attached to order: Ensure upload completed before adding to cart