Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add TypeScript code variant to walkthroughs #5635

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 97 additions & 0 deletions docs/walkthroughs/01-installing-slate.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,15 +28,38 @@ import { Slate, Editable, withReact } from 'slate-react'

Before we use those imports, let's start with an empty `<App>` component:

{% tabs %}

{% tab title="JavaScript" %}

```jsx
// Define our app...
const App = () => {
return null
}
```

{% endtab %}

{% tab title="TypeScript" %}

```tsx
// Define our app...
const App = () => {
return null
}
```

{% endtab %}

{% endtabs %}

The next step is to create a new `Editor` object. We want the editor to be stable across renders, so we use the `useState` hook [without a setter](https://github.com/ianstormtaylor/slate/pull/3925#issuecomment-781179930):

{% tabs %}

{% tab title="JavaScript" %}

```jsx
const App = () => {
// Create a Slate editor object that won't change across renders.
Expand All @@ -45,6 +68,22 @@ const App = () => {
}
```

{% endtab %}

{% tab title="TypeScript" %}

```tsx
const App = () => {
// Create a Slate editor object that won't change across renders.
const [editor] = useState(() => withReact(createEditor()))
return null
}
```

{% endtab %}

{% endtabs %}

Of course we haven't rendered anything, so you won't see any changes.

> If you are using TypeScript, you will also need to extend the `Editor` with `ReactEditor` and add annotations as per the documentation on [TypeScript](../concepts/12-typescript.md). The example below also includes the custom types required for the rest of this example.
Expand All @@ -70,6 +109,10 @@ Next up is to render a `<Slate>` context provider.

The provider component keeps track of your Slate editor, its plugins, its value, its selection, and any changes that occur. It **must** be rendered above any `<Editable>` components. But it can also provide the editor state to other components like toolbars, menus, etc. using the `useSlate` hook.

{% tabs %}

{% tab title="JavaScript" %}

```jsx
const initialValue = [
{
Expand All @@ -85,6 +128,29 @@ const App = () => {
}
```

{% endtab %}

{% tab title="TypeScript" %}

```tsx
const initialValue: Descendant[] = [
{
type: 'paragraph',
children: [{ text: 'A line of text in a paragraph.' }],
},
]

const App = () => {
const [editor] = useState(() => withReact(createEditor()))
// Render the Slate context.
return <Slate editor={editor} initialValue={initialValue} />
}
```

{% endtab %}

{% endtabs %}

You can think of the `<Slate>` component as providing a context to every component underneath it.

> Slate Provider's "value" prop is only used as initial state for editor.children. If your code relies on replacing editor.children you should do so by replacing it directly instead of relying on the "value" prop to do this for you. See [Slate PR 4540](https://github.com/ianstormtaylor/slate/pull/4540) for a more in-depth discussion.
Expand All @@ -95,6 +161,10 @@ By having a shared context, those other components can execute commands, query t

The next step is to render the `<Editable>` component itself. The component acts like `contenteditable`; anywhere you render it will render an editable richtext document for the nearest editor context.

{% tabs %}

{% tab title="JavaScript" %}

```jsx
const initialValue = [
{
Expand All @@ -114,6 +184,33 @@ const App = () => {
}
```

{% endtab %}

{% tab title="TypeScript" %}

```tsx
const initialValue: Descendant[] = [
{
type: 'paragraph',
children: [{ text: 'A line of text in a paragraph.' }],
},
]

const App = () => {
const [editor] = useState(() => withReact(createEditor()))
return (
// Add the editable component inside the context.
<Slate editor={editor} initialValue={initialValue}>
<Editable />
</Slate>
)
}
```

{% endtab %}

{% endtabs %}

There you have it!

That's the most basic example of Slate. If you render that onto the page, you should see a paragraph with the text `A line of text in a paragraph.` And when you type, you should see the text change!
Loading