Installation

To use the tldraw SDK, first install the tldraw package:

npm i tldraw

Now import and use the Tldraw component inside of any React component.

import { Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

export default function () {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw />
		</div>
	)
}

Wrapper

It's important that the Tldraw component is wrapped in a parent container that has an explicit size. Its height and width are set to 100%, so it will fill its parent container.

CSS

In addition to the Tldraw component itself, you should also import the tldraw.css file from the tldraw package.

import 'tldraw/tldraw.css'

You can alternatively import this file inside of another CSS file using the @import syntax.

@import url('tldraw/tldraw.css');

If you'd like to deeply change the way that tldraw looks, you can copy the tldraw.css file into a new CSS file, make your changes, and import that instead.

Fonts

We also use Inter as the default tldraw font. You can import this font however you like (or use a different font!) but here's the CSS import from Google fonts that we use:

@import url('https://fonts.googleapis.com/css2?family=Inter:wght@500;700&display=swap');

HTML

If you're using the Tldraw component in a full-screen app, you probably also want to update your index.html's meta viewport element as shown below.

<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

This may not be critical to Tldraw performing correctly, however some features (such as safe area positioning) will only work correctly if these viewport options are set.

License

If you have purchased a business license, you can register your license key using the Tldraw component's licenseKey prop. This will disable the "Made with tldraw" link while your license is active.

<Tldraw licenseKey={YOUR_LICENSE_KEY} />

To learn more about the license and license key, visit our pricing page.

Usage in Frameworks

Visit our framework examples repository to see examples of tldraw being used in various frameworks.

Static Assets

In order to use the Tldraw component, the app must be able to find certain assets. These are contained in the embed-icons, fonts, icons, and translations folders. We offer a few different ways of making these assets available to your app.

Using a bundler

If you're using a bundler like webpack or rollup, you can import the assets directly from the @tldraw/assets package. Your bundler should be able to copy across the assets with your bundle, and insert the correct URLs in their place.

There are three options:

• import {getAssetUrlsByImport} from '@tldraw/assets/imports': import asset files using import statements. You'll need to configure your bundler to treat imports of .svg, .png, .json, and .woff2 files as external assets.
• import {getAssetUrlsByImport} from '@tldraw/assets/imports.vite': import asset files, appending ?url to the asset path. This works correctly with vite without any extra configuration needed.
• import {getAssetUrlsByMeta} from '@tldraw/assets/urls': get asset urls using new URL(path, import.meta.url). This is a standards-based approach that works natively in most modern browsers & bundlers.

Call the function, and pass the resulting assetUrls into the Tldraw component:

import { getAssetUrlsByMetaUrl } from '@tldraw/assets/urls'

const assetUrls = getAssetUrlsByMetaUrl()

<Tldraw assetUrls={assetUrls} />

Using a public CDN

By default we serve these assets from a public CDN. Everything should work out of the box and is a good way to get started.

If you would like to customize some of the assets you can pass the customizations to our Tldraw component. For example, to use a custom icon for the hand tool you can do the following:

const assetUrls = {
    icons: {
        'tool-hand': './custom-tool-hand.svg',
    },
}

<Tldraw assetUrls={assetUrls} />

This will use the custom icon for the hand tool and the default assets for everything else.

Self-hosting static assets

If you want more flexibility you can also host these assets yourself:

1. Download the embed-icons, fonts, icons, and translations folders from the assets folder of the tldraw repository.
2. Place the folders in your project's public path.
3. Pass assetUrls prop to our <Tldraw/> component to let the component know where the assets live.

You can use our getAssetUrls helper function from the @tldraw/assets package to generate these urls for you.

import { getAssetUrls } from '@tldraw/assets/selfHosted'

const assetUrls = getAssetUrls()

<Tldraw assetUrls={assetUrls} />

While these files must be available, you can overwrite the individual files: for example, by placing different icons under the same name or modifying / adding translations.

If you use a CDN for hosting these files you can specify the base url of your assets. To recreate the above option of serving the assets from our CDN you would do the following:

import { getDefaultCdnBaseUrl } from 'tldraw'

const assetUrls = getAssetUrls({
	baseUrl: getDefaultCdnBaseUrl(),
})

Subcomponents

The Tldraw component combines two lower-level components: TldrawEditor and TldrawUi. If you want to have more granular control, you can use those lower-level components directly. See this example for reference.

Customize the default components

You can customize the appearance of the tldraw editor and ui using the Tldraw (or TldrawEditor) component's components prop.

const components: TLComponents = {
	Background: YourCustomBackground,
	SvgDefs: YourCustomSvgDefs,
	Brush: YourCustomBrush,
	ZoomBrush: YourCustomBrush,
	CollaboratorBrush: YourCustomBrush,
	Cursor: YourCustomCursor,
	CollaboratorCursor: YourCustomCursor,
	CollaboratorHint: YourCustomCollaboratorHint,
	CollaboratorShapeIndicator: YourCustomdicator,
	Grid: YourCustomGrid,
	Scribble: YourCustomScribble,
	SnapLine: YourCustomSnapLine,
	Handles: YourCustomHandles,
	Handle: YourCustomHandle,
	CollaboratorScribble: YourCustomScribble,
	ErrorFallback: YourCustomErrorFallback,
	ShapeErrorFallback: YourCustomShapeErrorFallback,
	ShapeIndicatorErrorFallback: YourCustomShapeIndicatorErrorFallback,
	Spinner: YourCustomSpinner,
	SelectionBackground: YourCustomSelectionBackground,
	SelectionForeground: YourCustomSelectionForeground,
	HoveredShapeIndicator: YourCustomHoveredShapeIndicator,
	// ...
}

<Tldraw components={components}/>

Versioning

The tldraw SDK does not follow semantic versioning. To learn more, read about how we do release versioning.