Twitch extension

This extension adds support for embedding Twitch videos, clips, and live channels into your editor.

Supported Content Types

Videos: Direct links to Twitch VODs
Clips: Links to Twitch clips
Channels: Links to live Twitch channels

Install

npm install @tiptap/extension-twitch

Settings

inline

Controls if the node should be handled inline or as a block.

Default: false

Twitch.configure({
  inline: false,
})

width

Controls the default width of added videos.

Default: 640

Twitch.configure({
  width: 480,
})

height

Controls the default height of added videos.

Default: 480

Twitch.configure({
  height: 320,
})

allowFullscreen

Allows the iframe to be played in fullscreen.

Default: true

Twitch.configure({
  allowFullscreen: false,
})

autoplay

Allows the iframe to start playing after the player is loaded.

Default: false

Twitch.configure({
  autoplay: true,
})

muted

Specifies whether the initial state of the video is muted. This is useful when autoplay is enabled, as most browsers require videos to be muted for autoplay to work.

Default: false

Twitch.configure({
  muted: true,
})

time

The time in the video where playback starts. Only applicable for video embeds, not for clips or channels. Format: 1h2m3s (hours, minutes, seconds).

Default: undefined

Twitch.configure({
  time: '1h2m3s',
})

parent

Specifies the domain that is embedding the Twitch player. This is required for the Twitch embed to function properly. You should set this to your domain.

Default: 'localhost'

Twitch.configure({
  parent: 'example.com',
})

addPasteHandler

Controls if the paste handler for Twitch video URLs should be added. When enabled, pasting a Twitch video URL will automatically create an embed.

Default: true

Twitch.configure({
  addPasteHandler: false,
})

HTMLAttributes

Pass custom HTML attributes to the iframe element.

Default: {}

Twitch.configure({
  HTMLAttributes: {
    class: 'custom-twitch-embed',
  },
})

Commands

setTwitchVideo(options)

Inserts a Twitch video iframe embed at the current position.

editor.commands.setTwitchVideo({
  src: 'https://www.twitch.tv/videos/1234567890',
  width: 640,
  height: 480,
})

Options

src - The URL of the Twitch video (optional)
width - The embed width (overrides the default option) (optional)
height - The embed height (overrides the default option) (optional)

Usage Examples

Basic Usage

import { useEditor, EditorContent } from '@tiptap/react'
import { StarterKit } from '@tiptap/starter-kit'
import { Twitch } from '@tiptap/extension-twitch'

const editor = useEditor({
  extensions: [
    StarterKit,
    Twitch.configure({
      parent: 'example.com',
    }),
  ],
  content: '<p>Hello World!</p>',
})

With Custom Configuration

const editor = useEditor({
  extensions: [
    StarterKit,
    Twitch.configure({
      parent: 'example.com',
      width: 800,
      height: 600,
      allowFullscreen: true,
      autoplay: false,
      addPasteHandler: true,
    }),
  ],
})

Programmatic Insertion

// Insert a Twitch video with the default dimensions
editor.commands.setTwitchVideo({
  src: 'https://www.twitch.tv/videos/1234567890',
})

// Insert with custom dimensions
editor.commands.setTwitchVideo({
  src: 'https://www.twitch.tv/videos/1234567890',
  width: 960,
  height: 540,
})

// Insert with custom autoplay and muted settings
editor.commands.setTwitchVideo({
  src: 'https://www.twitch.tv/videos/1234567890',
  autoplay: true,
  muted: true,
})

// Insert with start time
editor.commands.setTwitchVideo({
  src: 'https://www.twitch.tv/videos/1234567890',
  time: '1h2m3s',
})

Attribute Overrides

You can override the extension options for individual embeds by specifying attributes when inserting the video. This allows you to have different settings for different embeds, while using the extension options as defaults:

// Extension configured with autoplay=false by default
Twitch.configure({
  parent: 'example.com',
  autoplay: false,
})

// But insert this specific video with autoplay enabled
editor.commands.setTwitchVideo({
  src: 'https://www.twitch.tv/videos/1234567890',
  autoplay: true, // Overrides the extension's autoplay option
  muted: true, // Ensures audio is muted
})

Supported URL Formats

The extension supports the following Twitch URL formats:

Videos

https://www.twitch.tv/videos/1234567890
https://twitch.tv/videos/1234567890

Clips

https://www.twitch.tv/examplechannel/clip/ExampleClipName-ABC123
https://twitch.tv/examplechannel/clip/ExampleClipName-ABC123
https://clips.twitch.tv/ExampleClipName-ABC123
https://www.clips.twitch.tv/ExampleClipName-ABC123

Channels

https://www.twitch.tv/examplechannel
https://twitch.tv/examplechannel

Paste Support

When addPasteHandler is enabled (default), you can simply paste a Twitch video URL into the editor, and it will automatically be converted to an embed.

Paste this URL: https://www.twitch.tv/videos/1234567890
↓
Automatically creates a Twitch embed node

Important Notes

The parent domain configuration is required for the Twitch embed to display properly. Make sure to set it to your actual domain.
Twitch embeds require the parent domain to be whitelisted on the Twitch side for security reasons.
The extension validates URLs before creating embeds to prevent invalid content.
Embeds are draggable and can be repositioned within the document.

Keyboard Shortcuts

Backspace or Delete on a selected Twitch embed will remove it
You can select a Twitch embed with keyboard navigation and arrow keys

Source code

packages/extension-twitch/

PreviouslyText

Next upYoutube