File Uploader validators

Custom validators allow you to add the necessary checks for uploaded files and collections. These validators are pure functions, meaning they have no side effects and do not depend on external state. In the current version, only synchronous validators are implemented. Validators are invoked at various stages during file handling: before, during, and after upload. If a validator returns an error, that error will be available in the errors field of all related events.

There are two ways to use custom validators:

1. File validator.
2. Collection validator.

File validator

Validators are needed to check the suitability of a file. You can create your own validator to check that the file is uploaded with a specified parameter: size, type, content, resolution, etc. For example, use a function that checks for the file type imagesOnly:

1
const imagesOnly = (outputEntry, api) => {
2
  if (!outputEntry.isImage) {
3
    return {
4
      message: api.l10n('file-is-not-an-image-type')
5
    }
6
  }
7
}

Where arguments:

• outputEntry - see OutputFileEntry for more details.
• ctx - context that provides access to the necessary fields and methods, such as attribute values from the uc-config element and the l10n method for localizing messages.

⚠️ Note: Access to the fileInfo object is only possible after a successful file upload. Therefore, you need to check the upload status and ensure it is success before attempting to access fileInfo.

To attach the validator:

1
const config = document.querySelector('uc-config')
2
3
config.fileValidators = [imagesOnly]

Collection validator

Custom validator for checking collections:

1
const hasAtLeastOneImage = (collection, api) => {
2
  const hasImage = collection.allEntries.some(file => file.isImage)
3
  if (!hasImage) {
4
    return {
5
      message: 'You need to select at least one image'
6
    }
7
  }
8
}

Where arguments:

• collection - Object describing the file collection, see OutputCollectionState for more details.
• api - Uploader API instance that provides access to the localization and configuration options needed for validation, see Uploader API for more details.

To attach the validator:

1
const config = document.querySelector('uc-config')
2
3
config.collectionValidators = [hasAtLeastOneImage]

Errors

Each error should be returned in the following format:

1
type CustomValidatorError = {
2
  message: string
3
  payload?: Record<string, unknown>
4
}

Where:

• message (required) — the error message that will be displayed to the user.
• payload (optional) — additional data that may be useful for error handling.

You can capture any error through event subscriptions. Each custom validator has an error of the type CUSTOM_ERROR.

1
const ctx = document.querySelector('uc-upload-ctx-provider')
2
3
ctx.addEventListener('change', event => {
4
  const errors = event.detail.errors
5
  // Here you can see all errors from the validator
6
})

l10n for custom validation

You need to extend your locale definitions to implement error handling with localization l10n. This allows you to provide localized error messages. Below is an example of adding a custom error message for a file type validation:

1. Import Locale Files:
   First, import your existing locale files. These files contain the default localized strings for your application.

1
import { default as en } from './locales/file-uploader/en.js'
2
import { default as fr } from './locales/file-uploader/fr.js'

2. Extend Locales:
   Use UC.defineLocale to extend the existing locales by adding a new key for the error message. This ensures that your application can handle the new error message in different languages.

1
UC.defineLocale('en', {
2
  ...en,
3
  ...{
4
    'file-is-not-an-image-type': 'File is not an image type'
5
  }
6
})
7
UC.defineLocale('fr', {
8
  ...fr,
9
  ...{
10
    'file-is-not-an-image-type': "Le fichier n'est pas une image"
11
  }
12
})
13
14
UC.defineComponents(UC)

3. Define a Custom Validator:
   Create a custom validator function that uses the l10n method from the Uploader API api to retrieve the localized error message. This ensures that the message is appropriately localized based on the current language setting.

1
const someFuncValidator = (outputEntry, api) => {
2
  return {
3
    message: api.l10n('file-is-not-an-image-type'),
4
    payload: { entry: outputEntry }
5
  }
6
}

You can efficiently create and connect your own validators to validate uploaded files and collections and handle any errors that arise, providing a high level of user experience and flexibility when validating data.