Skip to main content
This guide will help you create your first LiveCodes playground using the SDK.

​
Basic Setup

​
1. Create a Container Element

First, add a container element to your HTML: 
<div id="container"></div>

​
2. Import and Initialize

Import the SDK and create a playground: 
import { createPlayground } from 'livecodes';

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

​
Your First Playground

Here’s a complete example with HTML, CSS, and JavaScript: 
import { createPlayground } from 'livecodes';

const playground = await createPlayground('#container', {
  config: {
    markup: {
      language: 'html',
      content: '<div id="app">Hello, World!</div>',
    },
    style: {
      language: 'css',
      content: `#app {
  font-family: sans-serif;
  padding: 20px;
  color: #333;
}`,
    },
    script: {
      language: 'javascript',
      content: `console.log('Hello from LiveCodes!');

document.querySelector('#app').addEventListener('click', () => {
  alert('You clicked me!');
});`,
    },
  },
});

// Run the code
await playground.run();

​
Container Options

You can specify the container in multiple ways:

​
CSS Selector (String)

const playground = await createPlayground('#container', options);
const playground = await createPlayground('.my-playground', options);
const playground = await createPlayground('[data-playground]', options);

​
HTMLElement

const element = document.getElementById('container');
const playground = await createPlayground(element, options);

​
Headless Mode (No Container)

In headless mode, you can omit the container: 
const playground = await createPlayground({
  headless: true,
  config: {
    markup: { language: 'html', content: '<h1>Headless</h1>' },
  },
});

​
Embed Options

Customize the playground behavior with embed options: 
const playground = await createPlayground('#container', {
  // Configuration object
  config: {
    markup: { language: 'markdown', content: '# Hello' },
    autoupdate: true,
  },
  
  // Load a starter template
  template: 'react',
  
  // Loading strategy
  loading: 'lazy', // 'lazy' | 'click' | 'eager'
  
  // App URL (for self-hosted instances)
  appUrl: 'https://livecodes.io',
  
  // Import from external source
  import: 'https://github.com/username/repo',
});

​
Loading Strategies

​
Lazy Loading (Default)

The playground loads when it enters the viewport: 
const playground = await createPlayground('#container', {
  loading: 'lazy',
  config: { /* ... */ },
});

​
Click-to-Load

Shows a “Click to load” screen: 
const playground = await createPlayground('#container', {
  loading: 'click',
  config: { /* ... */ },
});

// Later, load manually
await playground.load();

​
Eager Loading

Loads immediately: 
const playground = await createPlayground('#container', {
  loading: 'eager',
  config: { /* ... */ },
});

​
Using Templates

Start with a pre-configured template: 
const playground = await createPlayground('#container', {
  template: 'react',
});

​
Interacting with the Playground

Once created, you can interact with the playground: 
const playground = await createPlayground('#container', {
  template: 'javascript',
});

// Run the code
await playground.run();

// Get the current code
const code = await playground.getCode();
console.log(code.script.content);

// Get the configuration
const config = await playground.getConfig();
console.log(config.markup.language);

// Format the code
await playground.format();

// Get a share URL
const shareUrl = await playground.getShareUrl();
console.log('Share URL:', shareUrl);

​
Watching Events

Listen to playground events: 
const playground = await createPlayground('#container', {
  template: 'javascript',
});

// Watch for code changes
const codeWatcher = playground.watch('code', ({ code, config }) => {
  console.log('Code changed!');
  console.log('Script content:', code.script.content);
});

// Watch for console output
const consoleWatcher = playground.watch('console', ({ method, args }) => {
  console[method](...args);
});

// Watch for when playground is ready
playground.watch('ready', ({ config }) => {
  console.log('Playground ready with config:', config);
});

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

​
Styling the Container

By default, the container gets some default styles. You can customize them: 
<div 
  id="container"
  style="height: 500px; border: 2px solid #ddd;"
  data-default-styles="false"
></div>
Or set the height via data attribute: 
<div id="container" data-height="600px"></div>

​
Complete Example

Here’s a complete HTML page with an embedded playground: 
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>LiveCodes Playground</title>
  <style>
    #container {
      height: 80vh;
      margin: 20px;
    }
  </style>
</head>
<body>
  <div id="container"></div>

  <script type="module">
    import { createPlayground } from 'https://cdn.jsdelivr.net/npm/livecodes';

    const playground = await createPlayground('#container', {
      config: {
        markup: {
          language: 'html',
          content: '<h1>Welcome to LiveCodes!</h1>',
        },
        style: {
          language: 'css',
          content: 'h1 { color: #4A90E2; font-family: sans-serif; }',
        },
        script: {
          language: 'javascript',
          content: 'console.log("LiveCodes is ready!");',
        },
      },
    });

    // Auto-run when loaded
    playground.watch('ready', async () => {
      await playground.run();
    });
  </script>
</body>
</html>

​
Next Steps

API Reference

Explore all available SDK methods and options

Methods

Learn about all playground methods

Events

Understand the event system

Types

Browse TypeScript type definitions