kopia lustrzana https://github.com/Tldraw/Tldraw
186 wiersze
6.0 KiB
Markdown
186 wiersze
6.0 KiB
Markdown
---
|
|
title: Installation
|
|
status: published
|
|
author: steveruizok
|
|
date: 3/22/2023
|
|
order: 1
|
|
---
|
|
|
|
## Installation
|
|
|
|
First, install the `tldraw` package:
|
|
|
|
```bash
|
|
npm i tldraw
|
|
```
|
|
|
|
> The tldraw SDK [does not follow semantic versioning](/releases-versioning).
|
|
|
|
## Usage
|
|
|
|
You can use the [Tldraw](?) component inside of any React component.
|
|
|
|
```tsx
|
|
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.
|
|
|
|
```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
|
|
|
|
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@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, { ssr: false })
|
|
```
|
|
|
|
### Using a bundler
|
|
|
|
If you're using a bundler like webpack or rollup, you can import the assets directly from the `assets` package. Here you can use `getAssetUrlsByMetaUrl` helper function:
|
|
|
|
```tsx
|
|
import { getAssetUrlsByMetaUrl } from '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. 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/exploded/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}/>
|
|
```
|