WordleBoard

WordleBoard is a custom Gradio component that delivers the familiar Wordle gameplay directly inside a Gradio Blocks app. It handles the full game loop: rendering the grid, tracking guesses, evaluating feedback, and emitting actions back to the Python backend.

Features

• Wordle-style grid rendered as a custom component
• Built-in Wordle rules for scoring guesses (correct, present, absent)
• Reset support and user feedback messaging
• Integrates with standard Gradio inputs (e.g. Textbox) for user guesses
• Compatible with Gradio’s custom component lifecycle (postprocess, examples)

Backend Usage

import gradio as gr
from gradio_wordleboard import WordleBoard

wordle_component = WordleBoard()
private_state = wordle_component.create_game_state()


def handle_guess(guess: str):
    global private_state
    private_state, public_state = wordle_component.apply_action({"action": "guess", "guess": guess}, private_state)
    return wordle_component.to_public_dict(public_state)


def handle_reset():
    global private_state
    private_state = wordle_component.create_game_state()
    return wordle_component.to_public_dict(wordle_component.public_from_private(private_state))


with gr.Blocks() as demo:
    board = WordleBoard(value=wordle_component.to_public_dict(wordle_component.public_from_private(private_state)))
    guess_box = gr.Textbox(label="Enter a guess", placeholder="Type a 5-letter word")
    submit_btn = gr.Button("Submit")
    reset_btn = gr.Button("Reset", variant="secondary")

    submit_btn.click(fn=handle_guess, inputs=guess_box, outputs=board, queue=False)
    reset_btn.click(fn=handle_reset, outputs=board, queue=False)

Frontend

• frontend/Index.svelte renders the game board and status message.
• frontend/Example.svelte shows a compact preview for use in gr.Examples.

Refer to the official Gradio guides for additional background on custom component concepts and frontend development workflows: Key Component Concepts, Frontend Guide, and FAQ.

Building and Publishing

• Prep: cd /Users/ben/code/wordle_gradio/wordleboard && uv run npm install --prefix frontend installs the Svelte deps the CLI expects (required once after scaffolding per the “create → dev → build → publish” flow in the custom-component guide Gradio Docs).
• Hot-reload demo: stay inside wordleboard/ and run uv run gradio component dev. The CLI spins up the backend + Vite frontend; follow the “Frontend Server” URL printed to the console to play with your Wordle UI live (Gradio Docs).
• Python demo app: for a quick sanity check without the dev server, uv run python demo/app.py launches the packaged Blocks example using the component.
• Build artifacts: when you’re happy, still in wordleboard/ run uv run gradio component build. This emits a wheel/tarball under dist/ plus regenerated docs, matching the documented build phase before publishing (Gradio Docs).
• Next steps: After confirming the build, you can uv run gradio component publish to push to PyPI/Spaces, or install the wheel elsewhere to consume the component.