Creating an extension

In order to create an extension you will need to create a bundle and upload it to either:

Extension Warehouse for publishing (Coming soon).
Extension Manager for local development

Bundle

A typical bundle has the following files:

index.html
manifest.json
main.js

If self-hosting, only the manifest.json needs to be supplied.

Example index.html files

Headless

<!DOCTYPE html>
<html>
<head>
    <title>Extension</title>
    <script type="application/javascript" src="https://cdn.habitat.sketchup.com/dist/sketchup-js-api/v2/sketchup-js-api.js"></script>
    <script type="module" src="./main.js"></script>
</head>
<body>
</body>
</html>

Modal, Floating and Sidebar

<!DOCTYPE html>
<html>
<head>
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Open+Sans:ital,wght@0,300..800;1,300..800&display=swap" rel="stylesheet">

    <title>Extension</title>
    <script type="application/javascript" src="https://cdn.habitat.sketchup.com/dist/sketchup-js-api/v2/sketchup-js-api.js"></script>
    <script type="module" src="./main.js"></script>
</head>
<body>
</body>
</html>

Want your application to look like SketchUp?

Include our experimental CSS in the head section of your HTML file.

  <link rel="stylesheet" href="https://cdn.habitat.sketchup.com/dist/experimental/css/latest/sketchup-extension.css">

Dark mode

On hosts that have a dark appearance, the stylesheet follows SketchUp’s light or dark setting. Everywhere else, pages are light. Its colors are --su-* custom properties, each with a light and a dark value — --su-bg, --su-bg-surface, --su-bg-header, --su-bg-hover, --su-bg-selected, --su-text, --su-text-secondary, --su-text-accent, --su-link, --su-border and --su-border-subtle. Use them in your own CSS, or light-dark() for colors they don’t cover, and your styles switch along with it:

.note { color: var(--su-text-secondary); border-top: 1px solid var(--su-border); }
.error { color: light-dark(#c0392b, #ff8a7a); }

light-dark() only takes colors. For anything else, such as lightening navy <img> icons, put the rule inside the same conditions the stylesheet uses, so it applies exactly when the page is dark:

@supports (-webkit-touch-callout: none) {
  @media (prefers-color-scheme: dark) {
    img.button { filter: invert(1) hue-rotate(180deg); }
  }
}

For anything drawn from JavaScript, such as a canvas, use the same conditions, and listen for the media query’s change event to follow a switch while the page is open:

const darkMode = matchMedia('(prefers-color-scheme: dark)');
const isDark = () => CSS.supports('-webkit-touch-callout', 'none') && darkMode.matches;
darkMode.addEventListener('change', () => redraw(isDark()));

Without the stylesheet

To follow SketchUp’s appearance the same way in a page that doesn’t load sketchup-extension.css, declare the color scheme like this, then use light-dark() and the conditions above:

:root { color-scheme: light; }
@supports (-webkit-touch-callout: none) {
  :root { color-scheme: light dark; }
}
body {
  background-color: light-dark(#f1f1f6, #252a2e);
  color: light-dark(#000000, #ffffff);
}

Staying light-only

To keep your extension light-only, add this to your own stylesheet, loaded after this one:

:root { color-scheme: light; }

A <meta name="color-scheme"> tag does not work for this, because the stylesheet overrides it. A light-only page should also leave out the dark-only rules shown above.

Common Issues

Cross-Origin Resource Sharing (CORS)

You may see that your icons won’t load inside of SketchUp for Web. This is most likely due to CORS. Read the MDN guide to setup valid CORS headers on your web server.

Local Development

For developing extensions with a local server (HTTPS, CORS, SSL certificates), see the Local Development guide. The Localhost tutorial walks through the full workflow step by step.