Webview

Sandboxed iframes

Webview Plugins can be used to create all kinds of interfaces using HTML and JS.

Create a Webview

You can only create one webview per slot.

// Create a panel that appears below the home screen toolbar
const panel = ctx.newWebview({
    slot: "after-home-screen-toolbar",
    fullWidth: true,
    autoHeight: true,
})

Options

interface WebviewOptions {
    slot: "screen" |
        "fixed" |
        "after-home-screen-toolbar" |
        "home-screen-bottom" |
        "schedule-screen-top" |
        "schedule-screen-bottom" |
        "anime-screen-bottom" |
        "after-anime-entry-episode-list" |
        "after-anime-episode-list" |
        "before-anime-entry-episode-list" |
        "manga-screen-bottom" |
        "manga-entry-screen-bottom" |
        "after-manga-entry-chapter-list" |
        "after-discover-screen-header" |
        "after-media-entry-details" |
        "after-media-entry-form"

    // Iframe options
    className?: string
    style?: string
    width?: string
    height?: string
    maxWidth?: string
    maxHeight?: string
    zIndex?: number
    // Iframe height is automatically adjusted to fit the webview content
    autoHeight?: boolean
    // Iframe width takes the entire available width
    fullWidth?: boolean
    hidden?: boolean

    // Applies when slot = "screen"
    sidebar?: {
        label: string,
        icon: string,
    }
    
    // Applies when slot = "fixed"
    window?: {
        draggable?: boolean
        defaultX?: number
        defaultY?: number
        defaultPosition?: "top-left" | "top-right" | "bottom-left" | "bottom-right"
        frameless?: boolean
    }
}

Screen Slot

A Webview created with the slot screen will be rendered in its own page.

// Create a screen webview with a sidebar button
const webview = ctx.newWebview({
    slot: "screen",
    fullWidth: true,
    autoHeight: true,
    sidebar: {
        label: "Notepad",
        icon: `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/><rect x="8" y="2" width="8" height="4" rx="1" ry="1"/></svg>`,
    },
})

Fixed Slot

const webview = ctx.newWebview({
    slot: "fixed",
    width: "100%",
    maxWidth: "1200px",
    height: "500px",
    window: {
        draggable: true,
        defaultPosition: "bottom-right",
    },
    hidden: true,
})

button.onClick(() => {
    webview.show()
})

Events

webview.onMount(() => {
    // Webview has been mounted on the screen
})

webview.onUnmount(() => {
    // Webview has been unmounted
})

webview.onLoad(() => {
    // Webview content has been loaded (after mount)
})

// Force the webview content to update
webview.update()

// Returns the path to the webview screen
webview.getScreenPath() // /webview?id=my-plugin

webview.hide()

webview.show()

Rendering

HTML

// Renders iframe with transparent background
webview.setContent(() => `
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <style>
        html {
            color-scheme: dark;
            overflow: hidden;
        }
        
        body {
            background: transparent;
            font-family: -apple-system, system-ui, sans-serif;
            margin: 0;
        }
    </style>
</head>
<body>

    <script>
        
    </script>
</body>
</html>
`)

Messages

$ui.register((ctx) => {
    const notes = ctx.state<Array<{ id: string, text: string, checked: boolean }>>([
        { id: "2", text: "Check discussion for latest episode", checked: true },
        { id: "1", text: "Watch the next season", checked: false },
    ])
    
    // Sync notes state with webview
    panel.channel.sync("notes", notes)
    
    panel.channel.on("toggle-note", (id) => {
        notes.set(prev => prev.map(n => n.id === id ? { ...n, checked: !n.checked } : n))
    })
    
    panel.setContent(() => `
<!DOCTYPE html>
<html lang="en">
<head>...</head>
<body>
    <script>
        window.webview.on("notes", (newNotes) => console.log(newNotes))
        
        function toggleNote(id) {
            window.webview.send("toggle-note", id)
        }
    </script>
</body>
</html>
    `)
})

Example

This example uses Preact, a lightweight React alternative suitable for webviews.

function init() {
    $ui.register((ctx) => {
        // In a real plugin, you'd likely load this from whatever resource
        const currentMedia = ctx.state({
            id: 101,
            title: "Frieren: Beyond Journey's End",
            cover: "https://s4.anilist.co/file/anilistcdn/media/anime/cover/large/bx154587-qQTzQnEJJ3oB.jpg"
        })

        const notes = ctx.state<Array<{ id: string, text: string, checked: boolean }>>([
            { id: "2", text: "Check discussion for latest episode", checked: true },
            { id: "1", text: "Watch the next season", checked: false },
        ])

        // Create the Webview
        const panel = ctx.newWebview({
            slot: "screen",
            fullWidth: true,
            autoHeight: true,
            sidebar: {
                label: "Notepad",
                icon: `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"/><rect x="8" y="2" width="8" height="4" rx="1" ry="1"/></svg>`,
            },
        })

        // Setup Communication
        // Automatically keep 'notes' and 'currentMedia' variables in sync with the webview
        panel.channel.sync("notes", notes)
        panel.channel.sync("media", currentMedia)

        // Handle events sent from the webview
        panel.channel.on("add-note", (text) => {
            console.log("Received note:", text)
            const newNote = { id: Date.now().toString(), text, checked: false }
            // Updating this state automatically sends the new value to the webview thanks to .sync()
            notes.set([...notes.get(), newNote])
            ctx.toast.success("Note added")
        })

        panel.channel.on("toggle-note", (id) => {
            notes.set(prev => prev.map(n => n.id === id ? { ...n, checked: !n.checked } : n))
        })

        panel.channel.on("delete-note", (id) => {
            notes.set(prev => prev.filter(n => n.id !== id))
        })

        // Render the UI
        panel.setContent(() => `
        <!DOCTYPE html>
        <html lang="en">
        <head>
            <meta charset="UTF-8">
            <style>
                html {
                    color-scheme: dark;
                    overflow: hidden;
                }
                :root { 
                --bg: #101010; 
                --card: #10161f; 
                --text: #e2e8f0; 
                --accent: #3b82f6;
                 }
                body {
                    background: transparent;
                    color: var(--text);
                    font-family: -apple-system, system-ui, sans-serif;
                    padding: 20px;
                    margin: 0;
                }
                .container {
                    max-width: 100%;
                    margin: 0 auto;
                    background: var(--card);
                    border-radius: 12px;
                    padding: 24px;
                    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
                }
                .header { display: flex; align-items: center; gap: 16px; margin-bottom: 24px; }
                .cover { width: 60px; height: 85px; border-radius: 6px; object-fit: cover; }
                h2 { margin: 0; font-size: 1.25rem; }
                
                .input-group { display: flex; gap: 8px; margin-bottom: 20px; }
                input {
                    flex: 1;
                    background: rgba(0,0,0,0.2);
                    border: 1px solid rgba(255,255,255,0.1);
                    color: white;
                    padding: 8px 12px;
                    border-radius: 6px;
                }
                button {
                    background: var(--accent);
                    color: white;
                    border: none;
                    padding: 8px 16px;
                    border-radius: 6px;
                    cursor: pointer;
                    font-weight: 500;
                }
                button:hover { opacity: 0.9; }
                
                .list { list-style: none; padding: 0; margin: 0; }
                .item {
                    display: flex;
                    align-items: center;
                    gap: 12px;
                    padding: 12px;
                    border-bottom: 1px solid rgba(255,255,255,0.05);
                }
                .item:last-child { border-bottom: none; }
                .item.checked span { text-decoration: line-through; opacity: 0.5; }
                .delete-btn {
                    background: transparent;
                    color: #ef4444;
                    padding: 4px;
                    margin-left: auto;
                    opacity: 0;
                    transition: opacity 0.2s;
                }
                .item:hover .delete-btn { opacity: 1; }
            </style>
        </head>
        <body>
            <div id="app"></div>

            <script type="module">
                import { h, render } from "https://esm.sh/preact@10.19.3"
                import { useState, useEffect } from "https://esm.sh/preact@10.19.3/hooks"
                import htm from "https://esm.sh/htm@3.1.1"
                
                const html = htm.bind(h)

                function App() {
                    // Initial state will be injected by the sync function
                    const [media, setMedia] = useState({ title: "Loading...", cover: "" })
                    const [notes, setNotes] = useState([])
                    const [inputText, setInputText] = useState("")

                    useEffect(() => {
                        if (!window.webview) return

                        // Listen to sync events from the plugin
                        const unsubNotes = window.webview.on("notes", (newNotes) => setNotes(newNotes))
                        const unsubMedia = window.webview.on("media", (newMedia) => setMedia(newMedia))

                        return () => {
                            unsubNotes()
                            unsubMedia()
                        }
                    }, [])

                    const addNote = (e) => {
                        e.preventDefault()
                        if (!inputText.trim()) return
                        
                        // Send event to plugin
                        window.webview.send("add-note", inputText)
                        setInputText("")
                    }

                    const toggleNote = (id) => window.webview.send("toggle-note", id)
                    const deleteNote = (id) => window.webview.send("delete-note", id)

                    return html\`
                        <div class="container">
                            <div class="header">
                                \${media.cover && html\`<img src=\${media.cover} class="cover" />\`}
                                <div>
                                    <div style="font-size: 0.85rem; opacity: 0.7; margin-bottom: 4px;">NOW VIEWING</div>
                                    <h2>\${media.title}</h2>
                                </div>
                            </div>

                            <form class="input-group" onSubmit=\${addNote}>
                                <input 
                                    value=\${inputText}
                                    onInput=\${e => setInputText(e.target.value)}
                                    placeholder="Add a reminder or note..."
                                />
                                <button type="submit">Add</button>
                            </form>

                            <ul class="list">
                                \${notes.map(note => html\`
                                    <li class="item \${note.checked ? "checked" : ""}">
                                        <input 
                                            type="checkbox" 
                                            checked=\${note.checked} 
                                            onChange=\${() => toggleNote(note.id)}
                                        />
                                        <span style="width:100%;">\${note.text}</span>
                                        <button class="delete-btn" onClick=\${() => deleteNote(note.id)}>
                                            ✕
                                        </button>
                                    </li>
                                \`)}
                                \${notes.length === 0 && html\`
                                    <div style="text-align: center; opacity: 0.3; padding: 20px;">
                                        No notes for this series yet
                                    </div>
                                \`}
                            </ul>
                        </div>
                    \`
                }

                render(html\`<\${App} />\`, document.getElementById("app"))
            </script>
        </body>
        </html>
    `)
    })
}

PreviousTray NextToast

Last updated 4 days ago

hashtagCreate a Webview

hashtagOptions

hashtagScreen Slot

hashtagFixed Slot

hashtagEvents

hashtagRendering

hashtagHTML

hashtagMessages

hashtagExample