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

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

At the moment the `@tldraw/tldraw` package is in beta. We also ship a canary version which is always up to date with the main branch of tldraw [repository](https://github.com/tldraw/tldraw).

## Beta

First, install the `@tldraw/tldraw` package using `@beta` for the latest beta release.

<CodeBlock code={{'yarn': 'yarn add @tldraw/tldraw@beta', 'npm': 'npm install @tldraw/tldraw@beta', 'pnpm': 'pnpm add @tldraw/tldraw@beta'}} />

## Canary

To get the very latest version, use the [latest canary release](https://www.npmjs.com/package/@tldraw/tldraw?activeTab=versions). Docs for the very latest version are also available at [canary.tldraw.dev](https://canary.tldraw.dev).

<CodeBlock code={{'yarn': 'yarn add @tldraw/tldraw@canary', 'npm': 'npm install @tldraw/tldraw@canary', 'pnpm': 'pnpm add @tldraw/tldraw@canary'}} />

## Usage

You can use the [Tldraw](?) component inside of any React component.

```tsx
import { Tldraw } from '@tldraw/tldraw'
import '@tldraw/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/tldraw` package.

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

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

```css
@import url('@tldraw/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:

```css
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;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.

```html
<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.

## Server Rendering

The [Tldraw](?) component can't be server-rendered. If you're using the component in a server-rendered framework (such as Next.js) then you need to import it dynamically.

```tsx
const Tldraw = dynamic(async () => (await import('@tldraw/tldraw')).Tldraw, { ssr: false })
```

### Using a bundler

If you're using a bundler like webpack or rollup, you can import the assets directly from the `@tldraw/assets` package. Here you can use `getAssetUrlsByMetaUrl` helper function:

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

const assetUrls = getAssetUrlsByMetaUrl()

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

## Usage in Frameworks

Visit our [framework examples repository](https://github.com/tldraw/examples) 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 public CDN

By default we serve these assets from a [public CDN called unpkg](https://unpkg.com/browse/@tldraw/assets@2.0.0-alpha.12/), so 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:

```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 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](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 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 unpkg you would do the following:

```ts
const assetUrls = getAssetUrls({
	baseUrl: 'https://unpkg.com/@tldraw/assets@2.0.0-alpha.12/',
})
```

## 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](https://github.com/tldraw/tldraw/blob/main/apps/examples/src/examples/ExplodedExample.tsx) 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.

```tsx

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}/>
```