npm package: @serlo/editor-web-component
Description: This is an early version of the web component wrapping the [Serlo Editor](https://de.serlo.org/editor). Be aware that we are actively working on both packages and thus there will be breaking changes in minor versions before version 1 is reached. The repos
Author: Serlo Education e.V.
Latest version: 0.17.1-presigned-url.0

# Serlo Editor as a web component [![License](https://img.shields.io/badge/License-Apache_2.0-blue)](https://opensource.org/license/apache-2-0) [![npm](https://img.shields.io/npm/v/@serlo/editor-web-component.svg)](https://www.npmjs.com/package/@serlo/editor-web-component)

This is an early version of the web component wrapping the [Serlo Editor](https://de.serlo.org/editor). Be aware that we are actively working on both packages and thus there will be breaking changes in minor versions before version 1 is reached. The repositories [serlo/serlo-editor-lit](https://github.com/serlo/serlo-editor-lit) and [serlo/block-serlo-editor-with-vue-js](https://github.com/serlo/block-serlo-editor-with-vue-js) show how this package can be used.

If you are using React, we recommend using the Serlo Editor as a [React component](https://www.npmjs.com/package/@serlo/editor). Please also read the documentation of all the properties we expose there. The latest supported attributes and properties of the editor-web-component can be found [here](https://github.com/serlo/frontend/blob/staging/packages/editor-web-component/src/editor-web-component.tsx#L22).

## Installation and usage

1. `yarn add @serlo/editor-web-component`
2. Register the web component `customElements.define('serlo-editor', EditorWebComponent)`.
3. Render the web component

Below is an example of how to use the web component in a Vue.js application.

```vue
<template>
  <div>
    <button @click="toggleMode">{{ isEditing ? 'READ' : 'EDIT' }}</button>
    <serlo-editor
      :mode="isEditing ? 'write' : 'read'"
      :initial-state="initialExampleState"
      @state-changed="handleStateChange"
    ></serlo-editor>
  </div>
</template>

<script>
import { defineComponent, ref } from 'vue'
import { EditorWebComponent } from '@serlo/editor-web-component'

customElements.define('serlo-editor', EditorWebComponent)

export default defineComponent({
  name: 'SerloEditorComponent',
  setup() {
    const isEditing = ref(false)
    const initialState = ref({
      plugin: 'rows',
      state: [
        {
          plugin: 'text',
          state: [
            {
              type: 'h',
              level: 1,
              children: [{ text: 'Example Heading' }],
            },
          ],
        },
      ],
    })

    const toggleMode = () => {
      isEditing.value = !isEditing.value
    }

    const handleStateChange = (event) => {
      console.log('New state:', event.detail.newState)
    }

    return {
      isEditing,
      initialState,
      toggleMode,
      handleStateChange,
    }
  },
})
</script>
```

To familiarize yourself with our JSON structure, for each plugin, you can look at example JSONs [here](https://github.com/serlo/documentation/wiki/Serlo-Editor-Initial-State-of-Plugins). You can also go to our editor [preview page](https://de.serlo-staging.dev/___editor_preview), enter any plugin and through the menu in the top right corner, click "copy plugin". If you paste it in your code editor, you will see the JSON structure of the plugin you selected through the toolbar.

If you want to display a certain plugin as an initial state of the Serlo Editor, we recommend importing the `pluginMenuEn` / `pluginMenuDe` object and `Plugin` enum. Check out the [documentation](https://github.com/serlo/frontend/tree/staging/packages/editor#pluginmenuen--pluginmenude-constant-and-plugin-enum) for more information.

```typescript
import { pluginMenuEn, Plugin } from '@serlo/editor'

const singleChoiceKey = Plugin.SingleChoiceExercise
const initialStateOfSingleChoice = pluginMenuEn[singleChoiceKey].initialState
```

## How to disable/remove plugins

The Serlo Editor Web Component allows you to customize which plugins are available in the editor. By default, it uses all available plugins (`defaultPlugins`), but you can modify this list to remove specific plugins.

```javascript
import { EditorPluginType, defaultPlugins } from '@serlo/editor-web-component'

// Filter out specific plugins like the video plugin here
const filteredPlugins = defaultPlugins.filter(
  (plugin) => plugin !== EditorPluginType.Video
)
```

Then you can pass the filteredPlugins to the plugins array of the editor-web-component via a property by holding a reference to the Serlo Editor or via HTML attribute as seen below.

```html
<serlo-editor plugins='["text", "image", ...]'> </serlo-editor>
```

The plugins attribute/property accepts an array of plugin types. You can reference EditorPluginType for all available plugin options. Note that upon first render, the object will be frozen. You can't change the available plugins dynamically, so make sure to filter out the plugins you don't want before the first render!

## Configuring file uploads

Configure custom presigned URL endpoint using HTML attribute:

```html
<serlo-editor
  presigned-url-endpoint="https://custom-api.example.com/presigned-url"
>
</serlo-editor>
```

## Shadow DOM vs. normal DOM

Version 0.10.3 was the last stable version where you can render the Serlo Editor within the Shadow DOM. All future versions will only work in the regular DOM and the editor expects window/document objects to be available! If you are already rendering your whole app within a Shadow Root, you could consider wrapping the Serlo Editor in an iFrame which should allow you to keep having a Shadow Root, while making the global window/document objects available and isolating the Serlo Editor styles from your existing styles completely.

### For versions <= 0.10.3

We give you the option whether you want to render the web-component within the Shadow DOM or not. Both have their pros and cons. Outside of the Shadow DOM, it's easier to run into style collisions. However, the Serlo Editor within the Shadow DOM is buggy in a lot of places, especially when it comes to focus management.
By default we are rendering the Serlo Editor within the normal DOM. If you want to render it within the Shadow DOM, you can pass `true` to the `use-shadow-dom` argument.

```html
<editor-web-component use-shadow-dom="true"></editor-web-component>
```

## Releasing a new version to npm

Bump the version number in the package.json and
the github workflow seen inside `editor-web-component.yaml` will take care of the publishing.

## Local development with editor package

Go to the `package.json` and use `"@serlo/editor": "workspace:*"` instead of a fixed version. This way, you don't need to release a new version of the editor every time you make a change in the repo.

## Linking for local development with integrations

In order to avoid publishing the editor to NPM or dealing with tarballs every time you need to test your changes in an integration locally, you can use `yalc` to link the editor web component package to your integration locally.

Prerequisites:

- Yalc: `yarn global add yalc`

Initial steps:

1. From this workspace -> run `yarn yalc:publish`
2. From consumer repo -> run `yalc add @serlo/editor-web-component`

After making some changes in the editor:

- From this workspace -> run `yarn yalc:publish` (pushes dist, updates version and cache)

To remove the local link to Serlo Editor:

- From consumer repo -> run `yalc remove @serlo/editor-web-component`

## License

[Apache License, Version 2.0](https://opensource.org/license/apache-2-0)

Copyright (c) 2025-present, Serlo Education