Playground API

The Playground interface represents the LiveCodes playground instance returned by createPlayground(). It exposes methods to interact with the playground programmatically.

Methods

load()

Loads the playground if not already loaded.

load

() => Promise<void>

When the embed option loading is set to "click", the playground is not loaded automatically. Instead, a screen is shown with a “Click to load” button. Calling the SDK method load() allows loading the playground.If the playground was not loaded, calling any other method will load the playground first before executing.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container", {
  loading: "click",
});

// Load the playground programmatically
await playground.load();

run()

Runs the result page after any required compilation for code.

run

() => Promise<void>

Executes the current code and displays the result page.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");
await playground.run();
// new result page is displayed

format()

Formats the code in the editors.

format

(allEditors?: boolean) => Promise<void>

Show parameters

allEditors

boolean

default:true

By default, the code in all editors (markup, style and script) is formatted. To format only the active editor, pass false.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");

// Format all editors
await playground.format();

// Format only active editor
await playground.format(false);

getShareUrl()

Gets a share URL for the current project.

Show parameters

shortUrl

boolean

default:false

By default, the URL has a long query string representing the compressed encoded config object. If set to true, a short URL is generated.

Show returns

url

string

The share URL for the current project.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");
const longUrl = await playground.getShareUrl();
const shortUrl = await playground.getShareUrl(true);

getConfig()

Gets a configuration object representing the playground state.

getConfig

(contentOnly?: boolean) => Promise<Config>

Show parameters

contentOnly

boolean

default:false

If true, returns only the content-related configuration (code, languages, etc.), excluding user preferences and app settings.

Show returns

config

Config

The configuration object representing the playground state. This can be used to restore state if passed as an EmbedOptions property when creating playgrounds, or can be manipulated and loaded in run-time using setConfig method.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");
const config = await playground.getConfig();
const contentOnlyConfig = await playground.getConfig(true);

setConfig()

Loads a new project using the passed configuration object.

setConfig

(config: Partial<Config>) => Promise<Config>

Show parameters

config

Partial<Config>

required

A partial configuration object to load. Only the specified properties will be updated.

Show returns

config

Config

The full configuration object after the update.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");
const config = {
  markup: {
    language: "html",
    content: "Hello World!",
  },
};
const newConfig = await playground.setConfig(config);
// new project loaded

getCode()

Gets the playground code for each editor (markup, style, script) and result page HTML.

getCode

() => Promise<Code>

Show returns

code

Code

An object containing the language, source code, and compiled code for each editor, plus the result page HTML.

Show structure

markup

object

Show child attributes

language

Language

The language used in the markup editor.

content

string

The source code in the markup editor.

compiled

string

The compiled code from the markup editor.

style

object

Show child attributes

language

Language

The language used in the style editor.

content

string

The source code in the style editor.

compiled

string

The compiled code from the style editor.

script

object

Show child attributes

language

Language

The language used in the script editor.

content

string

The source code in the script editor.

compiled

string

The compiled code from the script editor.

result

string

The HTML of the result page.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");
const code = await playground.getCode();

// Source code, language and compiled code for the script editor
const { content, language, compiled } = code.script;

// Result page HTML
const result = code.result;

show()

Shows the selected panel.

show

(panel: EditorId | 'editor' | 'result' | 'toggle-result' | Tool['name'], options?: ShowOptions) => Promise<void>

Show parameters

panel

string

required

The panel to show. Can be one of:

"markup" | "style" | "script" - Show specific editor
"editor" - Show the editor pane
"result" - Show the result pane
"toggle-result" - Toggle the result pane
"console" | "compiled" | "tests" - Show specific tool

options

ShowOptions

Show properties

full

boolean

If true, shows the panel in full screen mode.

line

number

For editor panels, scroll to this line number.

column

number

For editor panels, scroll to this column number.

zoom

1 | 0.5 | 0.25

For result panel, set the zoom level.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");

// Show the style editor
await playground.show("style");

// Toggle result pane
await playground.show("toggle-result");

// Show result in full screen
await playground.show("result", { full: true });

// Show script editor at line 10
await playground.show("script", { line: 10 });

// Show result at 50% zoom
await playground.show("result", { zoom: 0.5 });

// Show console in full screen
await playground.show("console", { full: true });

runTests()

Runs project tests (if present) and gets test results.

runTests

() => Promise<{ results: TestResult[] }>

Show returns

results

TestResult[]

An array of test results.

Show TestResult structure

status

'pass' | 'fail' | 'skip'

The test status.

duration

number

Test execution time in milliseconds.

errors

string[]

Array of error messages (if any).

testPath

string[]

Path to the test in the test suite.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");
const { results } = await playground.runTests();

results.forEach((result) => {
  console.log(result.status); // "pass", "fail", or "skip"
  console.log(result.errors); // array of error strings
});

watch()

Allows watching for various playground events.

watch

WatchFn

Takes 2 arguments: event name and a callback function that will be called on every event.Event name can be one of: "load" | "ready" | "code" | "console" | "tests" | "destroy"In some events, the callback function receives an object with relevant data.Returns an object with a remove() method to stop watching the event.

Watch Events

load

(event: 'load', fn: () => void) => { remove: () => void }

Called when the playground first loads.

ready

(event: 'ready', fn: (data: { config: Config }) => void) => { remove: () => void }

Called when a new project is loaded (including when imported) and the playground is ready to run.

code

(event: 'code', fn: (data: { code: Code; config: Config }) => void) => { remove: () => void }

Called when the playground content changes. This includes changes in:

Code (in editors)
Editor languages
CSS processors
External resources
Project info
Custom settings
Project title
Test code

console

(event: 'console', fn: (data: { method: string; args: any[] }) => void) => { remove: () => void }

Called on every console output in the result page.

tests

(event: 'tests', fn: (data: { results: TestResult[]; error?: string }) => void) => { remove: () => void }

Called when tests run.

destroy

(event: 'destroy', fn: () => void) => { remove: () => void }

Called when the playground is destroyed.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");

const codeWatcher = playground.watch("code", ({ code, config }) => {
  // This will run on every code change
  console.log("code:", code);
  console.log("config:", config);
});

const consoleWatcher = playground.watch("console", ({ method, args }) => {
  // This will run on every console output
  console[method](...args);
});

const testsWatcher = playground.watch("tests", ({ results }) => {
  // This will run when tests run
  results.forEach((testResult) => {
    console.log("status:", testResult.status);
    console.log(testResult.errors);
  });
});

// Remove watchers when done
codeWatcher.remove();
consoleWatcher.remove();
testsWatcher.remove();

onChange()

Runs a callback function when code changes.

Deprecated: Use the watch method instead.

onChange

(fn: (data: { code: Code; config: Config }) => void) => { remove: () => void }

deprecated

Registers a callback that runs when code changes.

exec()

Executes custom commands.

exec

(command: APICommands, ...args: any[]) => Promise<{ output: any } | { error: string }>

Show parameters

command

'setBroadcastToken' | 'showVersion'

required

The command to execute.

args

any[]

Command arguments.

Show returns

result

{ output: any } | { error: string }

The command result or error.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");

// Show LiveCodes version
const versionResult = await playground.exec("showVersion");

// Set broadcast token
const tokenResult = await playground.exec("setBroadcastToken", "my-token");

destroy()

Destroys the playground instance and removes event listeners.

destroy

() => Promise<void>

Further calls to any SDK methods will throw an error after destruction.

import { createPlayground } from "livecodes";

const playground = await createPlayground("#container");

await playground.destroy();
// Playground destroyed
// Any further SDK call throws an error

Type Definitions

interface Playground {
  load: () => Promise<void>;
  run: () => Promise<void>;
  format: (allEditors?: boolean) => Promise<void>;
  getShareUrl: (shortUrl?: boolean) => Promise<string>;
  getConfig: (contentOnly?: boolean) => Promise<Config>;
  setConfig: (config: Partial<Config>) => Promise<Config>;
  getCode: () => Promise<Code>;
  show: (
    panel: EditorId | 'editor' | 'result' | 'toggle-result' | Tool['name'],
    options?: { full?: boolean; line?: number; column?: number; zoom?: Config['zoom'] }
  ) => Promise<void>;
  runTests: () => Promise<{ results: TestResult[] }>;
  onChange: (fn: (data: { code: Code; config: Config }) => void) => { remove: () => void };
  watch: WatchFn;
  exec: (command: APICommands, ...args: any[]) => Promise<{ output: any } | { error: string }>;
  destroy: () => Promise<void>;
}

Core API

Methods

Events

Methods

load()

run()

format()

getShareUrl()

getConfig()

setConfig()

getCode()

show()

runTests()

watch()

Watch Events

onChange()

exec()

destroy()

Type Definitions

Build docs developers (and LLMs) love

Core API

Methods

Events

​Methods

​load()

​run()

​format()

​getShareUrl()

​getConfig()

​setConfig()

​getCode()

​show()

​runTests()

​watch()

​Watch Events

​onChange()

​exec()

​destroy()

​Type Definitions

Build docs developers (and LLMs) love

Methods

load()

run()

format()

getShareUrl()

getConfig()

setConfig()

getCode()

show()

runTests()

watch()

Watch Events

onChange()

exec()

destroy()

Type Definitions