upstream-tldraw/apps/docs/content/getting-started/installation.mdx

---
title: Installation
status: published
author: steveruizok
date: 3/22/2023
order: 1
keywords:
  - hello world
---

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

```bash
npm install tldraw
```

Now import and use the [Tldraw](?) component inside of any React component. You will need React 18 or 19.

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

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

### Wrapper

The [Tldraw](?) component must be wrapped in a parent container with an explicit size. Its height and width are set to `100%`, so it will fill its parent container.

### Accessing the editor

Use the `onMount` prop to access the [Editor](?) instance when it's ready:

```tsx
function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw
				onMount={(editor) => {
					// Do something with the editor
					editor.selectAll()
				}}
			/>
		</div>
	)
}
```

The callback can return a cleanup function that runs when the editor unmounts.

### CSS

In addition to the [Tldraw](?) component itself, you should also import the `tldraw.css` file from the `tldraw` package.

```tsx
import 'tldraw/tldraw.css'
```

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

```css
@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

The tldraw SDK bundles its own fonts for shapes: IBM Plex (Sans, Serif, Mono) and Shantell Sans (for draw-style text). These are loaded automatically from the CDN or self-hosted [static assets](#Static-assets).

The tldraw UI will inherit its font family. You can set this to any font you like. For example, to use Inter:

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

.tl-container {
	font-family: 'Inter', sans-serif;
}
```

### HTML

If you're using the [Tldraw](?) component in a full-screen app, update your `index.html`'s meta viewport element as shown below.

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

Without these viewport options, some features like safe area positioning won't work correctly.

## License

If you have a [license key](https://tldraw.dev/pricing), you can pass your key to the `licenseKey` prop.

```tsx
<Tldraw licenseKey={YOUR_LICENSE_KEY} />
```

To learn more about the license and license key, visit [our pricing page](https://tldraw.dev/pricing).

## Static assets

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 will copy 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](https://vitejs.dev/guide/assets#explicit-url-imports) without any extra configuration needed.
- `import {getAssetUrlsByMetaUrl} 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:

```tsx
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. This works without configuration and is a good starting point.

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:

```tsx
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 assets

You can also host these assets yourself:

1. Download the `embed-icons`, `fonts`, `icons`, and `translations` folders from the [assets folder](https://github.com/tldraw/tldraw/tree/main/assets) 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.

```tsx
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 by modifying or 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:

```ts
import { getDefaultCdnBaseUrl } from 'tldraw'

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

## Subcomponents

The [Tldraw](?) component combines two lower-level components: [TldrawEditor](?) and [TldrawUi](?). If you want more granular control, you can use those lower-level components directly. See the [exploded example](/examples/configuration/exploded) for reference.

### Customizing components

You can customize the appearance of the tldraw editor and UI using the [Tldraw](?) (or [TldrawEditor](?)) component's `components` prop. This prop accepts a [TLComponents](?) object, which combines [TLEditorComponents](?) (canvas-level components like the background and grid) with [TLUiComponents](?) (UI elements like toolbar, menus, and panels).

```tsx
import { TLComponents } from 'tldraw'

const components: TLComponents = {
	// Editor components
	Background: YourCustomBackground,
	Grid: YourCustomGrid,

	// UI components
	Toolbar: YourCustomToolbar,
	MainMenu: YourCustomMainMenu,
	StylePanel: YourCustomStylePanel,
	ContextMenu: YourCustomContextMenu,
}

<Tldraw components={components} />
```

Canvas overlay elements like the selection foreground, brush, snap indicators, and scribble are rendered via the [OverlayUtil](?) system rather than React components. You can customize them by extending the built-in overlay utils and passing them via the `overlayUtils` prop.

See the [TLEditorComponents](?) and [TLUiComponents](?) type definitions for the complete list of customizable components.

## Versioning

The tldraw SDK does not follow semantic versioning. To learn more, read about how we do [release versioning](/releases).