Companion Preset Category File

The rule of thumb: If a file for your category already exists → edit it directly. If no file exists for your category → use this skill to create one and wire it up.

Pattern Overview

src/
  presets.ts                        ← aggregator (imports + combines all categories)
  presets/
    preset-{category-a}.ts          ← one file per preset category
    preset-{category-b}.ts
    preset-utils.ts                 ← CompanionPresetExt / CompanionPresetDefinitionsExt types

index.ts calls:

this.setPresetDefinitions(GetPresetList(this))

GetPresetList() (in presets.ts) calls each category's GetPresets{Category}(), stores the typed result in a local variable, spreads all results into one combined object, and returns it.

Pattern 1 — The Preset Category File

Imports

import { CompanionPresetExt, btn, colorWhite, colorBlack, colorLightGray } from './preset-utils.js'
import { ActionId{RelatedCategory} } from '../actions/action-{related-category}.js'

Always use .js extensions on relative imports — this is ESM. Import btn from preset-utils.js to use the shared button helper for simple presets. Import color constants when defining a button inline.

Enum of Preset IDs

Every preset file exports an enum that names all its presets. This enum is the key type for the return object and is re-exported to the aggregator.

export enum PresetIdMyCategory {
	myPreset = 'myCategory_myPreset',
	anotherPreset = 'myCategory_anotherPreset',
}

Convention: enum member names are camelCase; string values follow '{category}_{presetName}' to namespace IDs and avoid collisions across categories.

The Factory Function — Two Forms

Without instance (static presets — most categories):

export function GetPresetsMyCategory(): {
	[id in PresetIdMyCategory]: CompanionPresetExt | undefined
} {
	const presets: { [id in PresetIdMyCategory]: CompanionPresetExt | undefined } = {
		[PresetIdMyCategory.myPreset]: {
			type: 'button',
			category: 'My Category',
			name: 'My Preset',
			style: {
				text: 'Button Label',
				size: '14',
				color: colorBlack,
				bgcolor: colorLightGray,
			},
			steps: [
				{
					down: [
						{
							actionId: ActionIdMyCategory.someAction,
							options: {},
						},
					],
					up: [],
				},
			],
			feedbacks: [],
		},

		[PresetIdMyCategory.anotherPreset]: {
			// ...
		},
	}

	return presets
}

With instance (when presets need dynamic data — participant lists, config values):

import { InstanceBaseExt } from '../utils.js'
import { ZoomConfig } from '../config.js'

export function GetPresetsMyCategory(instance: InstanceBaseExt<ZoomConfig>): {
	[id in PresetIdMyCategory]: CompanionPresetExt | undefined
} {
	const presets: { [id in PresetIdMyCategory]: CompanionPresetExt | undefined } = {
		[PresetIdMyCategory.myPreset]: {
			type: 'button',
			category: 'My Category',
			name: instance.config.someConfigValue ?? 'Default Name',
			// ...
		},
	}

	return presets
}

Use the instance form only when required — preset-recording.ts is a no-instance example; preset-participants.ts is an instance example.

Why enum over plain string keys?

• TypeScript catches duplicate IDs at compile time — two enum members cannot have the same string value without a type error
• Rename-refactoring works across the whole codebase via IDE tooling
• The aggregator's union type enforces that every enum member is covered in the combined object
• actionId references inside steps are already typed enums — preset IDs should follow the same discipline

Pattern 2 — The Aggregator (presets.ts)

presets.ts has three responsibilities:

1. Import every category's enum and factory function
2. Call each factory, store the typed result in a local variable
3. Build a combined object (spread all categories), cast, and return it

1. Import the enum and factory

import { PresetIdMyCategory, GetPresetsMyCategory } from './presets/preset-my-category.js'

2. Call the factory and type the local variable

Inside GetPresetList(), alongside the other factory calls:

// no-instance form:
const presetsMyCategory: { [id in PresetIdMyCategory]: CompanionPresetExt | undefined } = GetPresetsMyCategory()

// instance form:
const presetsMyCategory: { [id in PresetIdMyCategory]: CompanionPresetExt | undefined } = GetPresetsMyCategory(instance)

3. Extend the union type on the combined presets object

The presets const has a mapped type whose key is a union of all category enums. Add the new enum to the union and its spread to the object:

const presets: {
	[id in PresetIdCategoryOne | PresetIdCategoryTwo | PresetIdMyCategory]: CompanionPresetExt | undefined // ← add new enum here
} = {
	...presetsCategoryOne,
	...presetsCategoryTwo,
	...presetsMyCategory, // ← add new spread here
}

return presets as CompanionPresetDefinitions

Why the union type is required: Unlike the old [id: string] index, the mapped type gives TypeScript visibility of every preset ID across the module. Adding an enum to the union without spreading (or vice versa) is a compile-time error.

as CompanionPresetDefinitions cast: The mapped type is more specific than CompanionPresetDefinitions — the cast is needed on the return value. This is identical to how actions.ts returns actions typed as CompanionActionDefinitions.

Step-by-Step Recipe

1. Create the file

src/presets/preset-{category}.ts

Use the template below (copy verbatim, replace all {placeholders}).

2. File template

import { CompanionPresetExt, btn, colorWhite, colorBlack } from './preset-utils.js'
import { ActionId{RelatedCategory} } from '../actions/action-{related-category}.js'

export enum PresetId{Category} {
  firstPreset = '{category}_firstPreset',
  secondPreset = '{category}_secondPreset',
}

export function GetPresets{Category}(): {
  [id in PresetId{Category}]: CompanionPresetExt | undefined
} {
  const presets: { [id in PresetId{Category}]: CompanionPresetExt | undefined } = {

    // Simple preset — use the btn() helper
    [PresetId{Category}.firstPreset]: btn(
      'First Preset',
      '{Category Display Name}',
      ActionId{RelatedCategory}.someAction,
      { targetType: 'roomIndex', roomIndex: 1 },
    ),

    // Inline preset — use when you need size '18', feedbacks, or multiple steps
    [PresetId{Category}.secondPreset]: {
      type: 'button',
      category: '{Category Display Name}',
      name: 'Second Preset',
      style: {
        text: 'Second Preset',
        size: '18',
        color: colorWhite,
        bgcolor: colorBlack,
      },
      steps: [
        {
          down: [
            {
              actionId: ActionId{RelatedCategory}.anotherAction,
              options: {},
            },
          ],
          up: [],
        },
      ],
      feedbacks: [],
    },

  }

  return presets
}

3. Import in presets.ts

Add at the top of presets.ts alongside the other imports:

import { PresetId{Category}, GetPresets{Category} } from './presets/preset-{category}.js'

4. Call the factory in GetPresetList()

Add inside GetPresetList(), alongside the other factory calls:

const presets{Category}: { [id in PresetId{Category}]: CompanionPresetExt | undefined } =
  GetPresets{Category}()
// or: GetPresets{Category}(instance)  ← if the factory needs instance

5. Extend the union type and spread into presets

In the presets const, add PresetId{Category} to the union and the spread to the object:

const presets: {
  [id in
    | /* ... existing enums ... */
    | PresetId{Category}   // ← add here
    ]: CompanionPresetExt | undefined
} = {
  /* ... existing spreads ... */
  ...presets{Category},   // ← add here
}

6. Build and verify

yarn build
# or: npm run build

Zero TypeScript errors means your new file is properly typed and wired.

Preset Button Shape

Full annotated reference for a CompanionPresetExt entry:

[PresetIdMyCategory.myPreset]: {
  type: 'button',                    // always 'button' for button presets
  category: 'My Category',           // groups presets in Companion UI by this label
  name: 'My Preset',                 // display name shown in the preset picker
  style: {
    text: 'Button Label',            // text rendered on the button face
    size: '14',                      // font size as string; use '18' for primary actions
    color: colorBlack,               // foreground color — import from './preset-utils.js'
    bgcolor: colorLightGray,         // background color — import from './preset-utils.js'
  },
  steps: [
    {
      down: [
        {
          actionId: ActionIdMyCategory.someAction,  // typed ActionId* enum value
          options: {},                               // action options object
        },
      ],
      up: [],                        // actions fired on button release (usually empty)
    },
  ],
  feedbacks: [],                     // feedback definitions ([] if none needed)
}

Shorthand: use btn() from preset-utils.js for simple presets (size '14', no feedbacks):

[PresetIdMyCategory.myPreset]: btn(
  'Button Label',
  'My Category',
  ActionIdMyCategory.someAction,
  { targetType: 'roomIndex', roomIndex: 1 },
),

Color Constants

All color constants live in src/presets/preset-utils.ts and are imported via './preset-utils.js'.

Currently defined:

If the color you need does not exist, add it to src/presets/preset-utils.ts as a new exported const before using it. Never use raw hex literals in preset files.

Common Mistakes

References

• src/presets.ts — the aggregator (authoritative wiring pattern, mirrors actions.ts)
• src/actions.ts — the action aggregator this pattern exactly mirrors
• src/presets/preset-join-flow.ts — no-instance preset category file example
• src/presets/preset-utils.ts — CompanionPresetExt type, colorWhite/colorBlack constants, btn() helper
• Sibling skill: companion-action-file-pattern — the parallel pattern this skill mirrors
• Sibling skill: companion-add-preset-to-category-file — use when category file already exists