Skip to main content
The LiveCodes SDK provides two main functions and several TypeScript types for embedding and controlling playgrounds.

​
Core Functions

​
createPlayground

Creates a LiveCodes playground instance.

​
Signatures

// Standard mode
function createPlayground(
  container: string | HTMLElement,
  options?: EmbedOptions
): Promise<Playground>

// Headless mode
function createPlayground(
  options: EmbedOptions & { view: 'headless' }
): Promise<Playground>

​
Parameters

​
container
string | HTMLElement
required
The container element or CSS selector where the playground will be rendered.In headless mode, this parameter is optional and can be omitted.
​
options
EmbedOptions
The embed options for configuring the playground.

​
Returns

​
Promise<Playground>
Playground
A promise that resolves to a Playground object with methods to interact with the playground.

​
Example

import { createPlayground } from 'livecodes';

// With CSS selector
const playground = await createPlayground('#container', {
  config: {
    markup: {
      language: 'html',
      content: '<h1>Hello!</h1>',
    },
  },
});

// With HTMLElement
const element = document.getElementById('container');
const playground = await createPlayground(element, { template: 'react' });

// Headless mode
const headless = await createPlayground({ headless: true });

​
getPlaygroundUrl

Generates a URL to a LiveCodes playground from the provided options.

​
Signature

function getPlaygroundUrl(options?: EmbedOptions): string

​
Parameters

​
options
EmbedOptions
The embed options to encode in the URL.

​
Returns

​
string
string
The URL of the playground as a string.

​
Example

import { getPlaygroundUrl } from 'livecodes';

const url = getPlaygroundUrl({
  config: {
    markup: {
      language: 'markdown',
      content: '# Hello World',
    },
  },
  template: 'typescript',
});

console.log(url);
// https://livecodes.io/#config=code/...

​
EmbedOptions

Configuration options for embedding a playground. 
interface EmbedOptions {
  appUrl?: string;
  params?: UrlQueryParams;
  config?: Partial<Config> | string;
  headless?: boolean;
  import?: string;
  lite?: boolean; // deprecated
  loading?: 'lazy' | 'click' | 'eager';
  template?: TemplateName;
  view?: 'split' | 'editor' | 'result' | 'headless'; // deprecated
}

​
Properties

​
appUrl
string
default:"https://livecodes.io"
The URL of the LiveCodes app to use. Useful for self-hosted instances or permanent URLs.
​
params
UrlQueryParams
URL query parameters that configure the playground. Alternative to using config.
params: { md: '# Hello World!' }
​
config
Partial<Config> | string
A configuration object or URL to a JSON file containing configuration.
config: {
  markup: { language: 'html', content: '<h1>Hi</h1>' },
  autoupdate: true,
}
Or:
config: 'https://example.com/config.json'
​
headless
boolean
default:false
If true, the playground loads in headless mode (no visible UI).
​
import
string
A resource to import from any supported source (GitHub, GitLab, gist, etc.).
import: 'https://github.com/username/repo'
​
loading
'lazy' | 'click' | 'eager'
default:"lazy"
Sets how the playground loads:
  • "lazy": Loads when entering viewport
  • "click": Shows “Click to load” screen
  • "eager": Loads immediately
​
template
TemplateName
A starter template to load (e.g., "react", "vue", "typescript", "python").See all available templates in the types documentation.
​
lite
boolean
default:false
Deprecated: Use config: { mode: "lite" } instead.
If true, loads the playground in lite mode.
​
view
'split' | 'editor' | 'result' | 'headless'
default:"split"
Deprecated: Use config.view instead. For headless mode use headless: true.
The default view for the playground.

​
Playground Interface

The Playground object returned by createPlayground provides methods to interact with the playground. 
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: string, options?: ShowOptions) => Promise<void>;
  runTests: () => Promise<{ results: TestResult[] }>;
  onChange: (fn: ChangeHandler) => { remove: () => void }; // deprecated
  watch: WatchFn;
  exec: (command: string, ...args: any[]) => Promise<any>;
  destroy: () => Promise<void>;
}
See the Methods documentation for detailed information about each method.

​
Config Interface

The configuration object that defines the playground state. 
interface Config extends ContentConfig, AppConfig, UserConfig {}

​
ContentConfig

Properties that define the project content:
​
title
string
default:"Untitled Project"
Project title used in the result page and meta tags.
​
description
string
default:""
Project description for search and meta tags.
​
markup
Editor
Configuration for the markup editor (HTML, Markdown, etc.).
markup: {
  language: 'markdown',
  content: '# Hello World',
}
​
style
Editor
Configuration for the style editor (CSS, SCSS, etc.).
​
script
Editor
Configuration for the script editor (JavaScript, TypeScript, etc.).
​
stylesheets
string[]
Array of external stylesheet URLs.
​
scripts
string[]
Array of external script URLs.
​
processors
Processor[]
CSS processors to enable (e.g., ["tailwindcss", "autoprefixer"]).
​
customSettings
CustomSettings
Custom settings for the project (import maps, types, etc.).
​
imports
Record<string, string>
Custom import maps for module resolution.
imports: {
  'moment': 'https://cdn.jsdelivr.net/npm/[email protected]/dist/moment.js'
}
​
types
Types
Custom TypeScript type declarations for better IntelliSense.
​
tests
Partial<Editor>
Configuration for tests.

​
AppConfig

Properties that define app behavior:
​
readonly
boolean
default:false
If true, editors are read-only.
​
allowLangChange
boolean
default:true
If false, hides the language selector UI.
​
view
'split' | 'editor' | 'result'
default:"split"
The default view for the playground.
​
mode
'full' | 'focus' | 'lite' | 'simple' | 'editor' | 'codeblock' | 'result'
default:"full"
The display mode for the playground.
​
tools
ToolsConfig
Configuration for the tools pane.
tools: {
  enabled: ['console', 'compiled'],
  active: 'console',
  status: 'open'
}
​
zoom
1 | 0.5 | 0.25
default:1
Result page zoom level.

​
UserConfig

User preferences and editor settings:
​
autoupdate
boolean
default:true
Auto-update result page on code change.
​
autosave
boolean
default:false
Auto-save project on code change.
​
delay
number
default:1500
Delay in milliseconds before auto-update/auto-save.
​
formatOnsave
boolean
default:false
Auto-format code on save.
​
theme
'light' | 'dark'
default:"dark"
App theme.
​
editor
'monaco' | 'codemirror' | 'codejar' | 'auto' | undefined
Code editor to use.
​
fontSize
number
Editor font size.
​
tabSize
number
default:2
Number of spaces per indentation level.
See the Types documentation for complete type definitions.

​
Code Interface

Represents the code in all editors and the result page. 
interface Code {
  markup: {
    language: Language;
    content: string;
    compiled: string;
  };
  style: {
    language: Language;
    content: string;
    compiled: string;
  };
  script: {
    language: Language;
    content: string;
    compiled: string;
  };
  result: string;
}

​
Language Type

Supported language names, aliases, and extensions: 
type Language = 
  | 'html' | 'htm'
  | 'markdown' | 'md'
  | 'javascript' | 'js'
  | 'typescript' | 'ts'
  | 'jsx' | 'tsx'
  | 'css' | 'scss' | 'sass' | 'less'
  | 'vue' | 'svelte' | 'react'
  | 'python' | 'py'
  // ... and many more
See the Types documentation for the complete list.

​
Next Steps

Methods

Explore all playground methods in detail

Events

Learn about the event system

Types

Browse complete TypeScript types

React Component

Use the React component

Build docs developers (and LLMs) love

Get started for freeTalk to us