Start typing to search...
Developer DocsAPI Reference
Back to withkoji.com

@withkoji/custom-vcc-sdk

The @withkoji/custom-vcc-sdk package enables you to implement custom controls for capturing user input on the frontend of your Koji app.

The Koji platform includes controls for standard elements, such as images, text, and sounds. With this package, you can build custom controls that are better suited for the application you are developing. For example, some Koji apps provide tile map editors, sound enhancers, or custom avatar creators to enhance the interactivity for customization.

Installation

Install the package in your Koji project.

npm install @withkoji/custom-vcc-sdk

Basic use

Building custom controls

Import and instantiate CustomVcc.

import CustomVcc from '@withkoji/custom-vcc-sdk'
const customVcc = new CustomVcc();

Assign event listeners for updates.

customVcc.onTheme((theme) => {
  // Listen to Koji theme to match the styles in your control
});

customVcc.onUpdate((props) => {
  // Listen to the control's current state
});

When the custom control has loaded, register it to trigger events from the parent editor.

customVcc.register(width, height);

When a user changes the value, update it and save the file.

customVcc.change(newValue);
customVcc.save();

Using custom controls

To make a custom control accessible to other Koji apps, you must make it available through a custom domain. After you publish the project, add a subdomain under the koji-vccs.com root domain.

Then, you can use the control in a Koji app in one of these ways.

  • (Recommended) With the @withkoji/core package, call the Koji.ui.capture.custom method with the subdomain name. For example:

    const music = await Koji.ui.capture.custom({ name: 'scloud' });

  • (Deprecated) With the @withkoji/vcc package, use the subdomain name as the VCC type. For example:

    "type": "custom<YOUR-SUBDOMAIN-NAME>"

Related resources