npm package: @ignitevideo/plugin-payloadcms
Description: Ignite Video Cloud plugin for Payload CMS
Author: tech@ignite.video
Latest version: 3.1.0

# ignite-payload-plugin

Ignite Video Cloud plugin for Payload CMS. This plugin provides a ready to use field for Payload CMS, to fetch video data from Ignite Video Cloud.

## Installation

```bash
pnpm add @ignitevideo/plugin-payloadcms
```

```bash
npm install @ignitevideo/plugin-payloadcms
```

```bash
yarn add @ignitevideo/plugin-payloadcms
```

### Beta Version

To install the latest beta version with new features:

```bash
pnpm add @ignitevideo/plugin-payloadcms@beta
```

## Plugin Integration

Import and insert the plugin into the Payload config

```javascript
import { igniteVideo } from '@ignitevideo/plugin-payloadcms'

export default buildConfig({
	plugins: [
		igniteVideo({
			authToken: '[YOUR-IGNITE-API-TOKEN]',
		}),
	],
})
```

### Plugin properties / parameters

#### `authToken` (string)

your Ignite Video Cloud API access token. Can be found under "API Integrations" in your Ignite admin UI

#### `enabled` (boolean)

(optional) Defines if the plugin is enabled. (Default: true)

#### `igniteUrl` (string)

(optional)your Ignite Video Cloud API URL. For all accounts, except for enterprise accounts this is `https://app.ignitevideo.cloud`

## Field Integration

Import and insert the field component

```javascript
import { igniteVideoSelect } from '@ignitevideo/plugin-payloadcms/fields'

const Pages: CollectionConfig = {
	slug: 'pages',
	fields: [
		{
			// ...other fields...
		},
		igniteVideoSelect({
			name: '[FIELD-NAME]',
		}),
		{
			// ...other fields...
		},
	],
}
```

### Field properties / paramenters

#### `name` (string)

the name of your video field in payload

#### `show` ('public' | 'private' | 'all')

(optional) Defines the visibility status of the videos to show in the selection (Default: "public")

#### `allowUpload` (boolean)

(optional) Defines if the user is allowed to upload videos directly from the field. If set to true, a upload button will be visible in the field. Your API token needs to have the necessary permissions to create videos in your Ignite account. (Default: false)

If you have set `categories` or `tags`, these will be assinged to uploaded videos via the plugin.

#### `label` (string)

(optional) Overwrites the default field label (Default: "Select video")

#### `required` (boolean)

(optional) Sets payload default field required attribute. (Default: false)

#### `categories` (string[] of category slugs)

(optional) Can be set to query the API for specific categories only. Categories provided in this array have an OR relationship.

#### `tags` (string[] of tag slugs)

(optional) Can be set to query the API for specific tags only. Tags provided in this array have an OR relationship.

#### `admin` (GroupField["admin"])

(optional) Can be set to override the admin settings for the root field (group field).

### Example field config

```javascript
igniteVideoSelect({
	name: 'hoverVideo',
	label: 'Choose the hover video',
	allowUpload: true,
	required: true,
	categories: ['website', 'app'],
	tags: ['loops', 'muted'],
})
```

## Video Selection Behavior

The video select field uses a search-based approach for optimal performance:

1. **Initial Load**: Shows the latest 10 videos from your Ignite account
2. **Search**: Type at least 3 characters to search across all videos
3. **Pre-selected Videos**: If a video is already selected that's not in the latest 10, it will be fetched automatically

This approach ensures fast load times even for accounts with thousands of videos.

## Changelog

### 3.1.0-beta.1

-   **New**: Search-based video selection - type to search instead of loading all videos
-   **New**: Shows latest 10 videos on initial load for quick access
-   **New**: Debounced search input (200ms) for better performance
-   **Improved**: Better error handling for API responses
-   **Improved**: Loading states with spinner indicator
-   **Fixed**: Video preview now persists after search selection

### 3.1.0-beta.2

-   **Fixed**: Video search now correctly filters results from the API using `where[title][like]`
-   **Fixed**: Selected video title no longer briefly replaced by ID after selecting a search result
-   **Fixed**: Previously selected videos that are not in the initial results are now fetched by ID