Visual Customization Controls (deprecated)

Important

Visual Customization Controls (VCCs) are deprecated and are included only for backwards compatibility. Use the Frontend UI/Capture component of the @withkoji/core package instead.

Visual Customization Controls (VCCs) enable users to quickly edit elements of your template on Koji. The control types and default values are defined in JSON files in your project. During remixes, the associated visual controls allow a user to enter or select a custom value.

Visual control for a text VCC and the associated .JSON file

Using VCCs

To use VCCs in your template, add a customization file to the .koji/customization folder of your project. The customization file defines the names, types, configuration options, and default values for VCCs used in the template.

JSON format of a Koji customization file

{
  "example":  { (1)
    "param":  "this is the value of the param"
  },
  "@@initialTransform": { (2)
    "example": {
      "param": "this is the placeholder text for new remixes"
    }
  },
  "@@editor":  [ (3)
    {
      "key":  "example", (4)
      "name":  "Example", (5)
      "icon":  "😄", (6)
      "source":  "example.json", (7)
      "fields":  [ (8)
        {
          "key":  "param", (9)
          "name":  "An Example Parameter", (10)
          "description": "My description of the parameter", (11)
          "type":  "image", (12)
          "typeOptions": { (13)

          }
        }
      ]
    }
  ]
}

<scope> – Section that defines the scope and default values for customizable elements. Default values are used in the published template.
@@initialTransform – (Optional) Section that defines the placeholder values for new remixes. For keys defined in this section, the placeholder value is used as the starting value for new remixes. For other keys, the VCC value from the remixed Koji is used.
@@editor – Section that defines how VCCs are displayed to remixers.
key – Scope used to access values in your template logic. Should match the filename.
name – Name displayed in the Koji editor for developers.
icon – (Optional) Icon displayed in the Koji editor for developers.
source – Filename from which to obtain values. Should be the same file, in most cases.
fields – Array of VCC definitions.
key – Key used to access the value in your template logic.
name – Display name of the element for remixers.
description – (Optional) Description of the element for remixers.
type – VCC type.
typeOptions – (Optional) Configuration options for the VCC. The available options vary by type.

VCC types

The Koji platform provides built-in VCCs for standard elements, such as images, text, and sounds. To provide more specialized customization types, you can use custom VCCs published on the Koji platform and you can build your own custom VCCs.

To compose higher-order controls, you can combine VCCs into arrays or objects. You can also combine arrays and objects to create more elaborate controls.

Built-in VCCs (alphabetical)

Standard VCC remix demo [template link]

boolean.html: toggle a Boolean value on or off (true or false).
color.html: select a color from a swatch or enter a color code (HEX, RGB, and HSL).
coordinate.html: specify a coordinate pair (x,y).
file.html: upload any file.
image.html: select an image by selecting from the available options, uploading, or entering a URL.
link-vcc.html: paste an external URL, create a new Koji from a template, or select an existing Koji from their profile.
media.html: select an image, file, sound, or video by selecting from the available options, uploading, or entering a URL.
3d-object.html: browse and import 3D objects from Google Poly.
range.html: drag a slider to specify a numeric value within a certain range.
secret.html: store sensitive data in a VCC without the value being visible when the project is remixed.
select.html: make a selection from a predefined list of options.
size.html: specify a (width, height) pair.
sound.html: select a sound either by selecting from the available options, uploading, or entering a URL.
text.html: change text by clicking the input field and entering the new text.
video.html: upload video files.

Custom VCC showcase

google-font.html: select a font family from Google Fonts.

VCC composition controls