# Installation
URL: https://vibewidget.dev/docs
Get up and running with Vibe Widget in seconds.
Get up and running with Vibe Widget in seconds. pip install vibe-widget Vibe Widget requires Python 3.9+ and an OpenRouter API key. export OPENROUTER_API_KEY=&#x27;your-key&#x27; Need help setting API keys in Jupyter? See this guide: https://docs.google.com/document/d/e/2PACX-1vST8sEHdo90NsTdTFNjLi27YFT-81u2WQa7--qr0u4yk2aByE6Q5WIj-p8JYueEING5-fNdFNu2Aa3t/pub Get an OpenRouter API key: https://openrouter.ai/ Quick start (3 minutes) pip install vibe-widget # macOS/Linux (temporary for current shell) export OPENROUTER_API_KEY=&quot;your-key&quot; # Windows PowerShell (temporary for current session) $env:OPENROUTER_API_KEY=&quot;your-key&quot; Widget PreviewOpen the live docs to see this interactive widget. import pandas as pd import vibe_widget as vw df = pd.read_csv(&quot;sales.csv&quot;) widget = vw.create(&quot;bar chart of revenue by region&quot;, df) widget If you want the key to persist across sessions, add the export line to your shell profile (for example ~/.zshrc or ~/.bashrc). Quick start Widget PreviewOpen the live docs to see this interactive widget. import pandas as pd import vibe_widget as vw df = pd.read_csv(&quot;sales.csv&quot;) widget = vw.create( &quot;scatter plot with brush selection, and a linked histogram&quot;, df, outputs=vw.outputs(selected_indices=&quot;indices of selected points&quot;) ) widget


# Configuration
URL: https://vibewidget.dev/docs/config
Configure model settings and API keys.
Configure model settings and API keys. Set defaults import vibe_widget as vw vw.config(model=&quot;openai/gpt-5.1-codex&quot;) vw.config(mode=&quot;premium&quot;, model=&quot;openrouter&quot;) vw.config(execution=&quot;approve&quot;) API key setup Get an OpenRouter API key: https://openrouter.ai/ Need help setting API keys in Jupyter? See this guide. export OPENROUTER_API_KEY=&#x27;your-key&#x27; $env:OPENROUTER_API_KEY=&quot;your-key&quot; import os from dotenv import load_dotenv import vibe_widget as vw load_dotenv() api_key = os.getenv(&quot;MY_SECRET_API_KEY&quot;) vw.config(api_key=api_key) We recommend avoiding hardcoded keys in notebooks to prevent accidental leaks. Models vw.models() vw.models(show=&quot;all&quot;) vw.models(verbose=False) Common configuration options vw.config( execution=&quot;auto&quot;, # &quot;auto&quot; or &quot;approve&quot; retry=2, # Runtime repair attempts agent_preset=&quot;project&quot;, agent_run={&quot;tier&quot;: 1}, bypass_row_guard=False, ) Privacy and telemetry Vibe Widget sends the following to the model provider: your prompt and theme prompt data schema (column names, dtypes) a small sample of rows (up to 3) outputs/inputs descriptors full widget code for edits, audits, and runtime fixes runtime error messages (when auto-fixing) No API keys are written to disk. Generated widgets and audit reports are stored locally in .vibewidget/.


# Create
URL: https://vibewidget.dev/docs/create
Create widgets from natural language prompts and data sources.
Create widgets from natural language prompts and data sources. Widget PreviewOpen the live docs to see this interactive widget. import vibe_widget as vw widget = vw.create( &quot;bar chart of revenue by region&quot;, df ) widget Themes Themes are natural-language design specs that guide code generation. vw.create(&quot;...&quot;, df, theme=&quot;financial_times&quot;) Use vw.theme(...) to generate a custom theme description and pass it in. Inputs, outputs, and actions You can also add inputs, outputs, and actions to wire widgets together or trigger behavior from Python. For the full model and examples, see Reactivity. Safety warning Widgets execute LLM-generated JavaScript in the notebook frontend. Treat generated code as untrusted. Use audits and your own verification when the output informs decisions.


# Edit
URL: https://vibewidget.dev/docs/edit
Iterate on generated widgets using code or the UI.
Editing is covered alongside creation and theming so you can iterate in the same flow. For creation + edits, see Create For theme-aware edits, see Theming


# Audit
URL: https://vibewidget.dev/docs/audit
Review widget code and behavior for risks, usability issues, and design gaps.
Audits review widget code and behavior through a set of lenses to surface risks, usability issues, and design gaps before you ship. Audit framework Each audit runs across domains and lenses so you get feedback that is both technical and experiential. DomainWhat It CoversKey QuestionsDATAInput, filtering, transformations, formatting. Subdomains: data.input, data.filtering, data.transformations, data.formatting.What goes in? What gets dropped? How is it changed?COMPUTATIONAlgorithms, parameters, assumptions. Subdomains: computation.algorithm, computation.parameters, computation.assumptions.What runs? With what settings? What does it assume?PRESENTATIONVisual encoding, scales, projection. Subdomains: presentation.encoding, presentation.scales, presentation.projection.How are results shown? What is hidden or over-emphasized?INTERACTIONTriggers, state, propagation. Subdomains: interaction.triggers, interaction.state, interaction.propagation.What changes on input? What persists? What updates downstream?SYSTEMAccessibility, performance, reliability. Subdomains: system.accessibility, system.performance, system.reliability.Is it usable for everyone? Is it fast and stable? Each domain is reviewed at a second level to pinpoint the issue scope, such as data.transformations or computation.parameters.bin_size, so fixes stay targeted and explainable. Audit lenses Lenses are the perspectives applied during auditing. You can think of them as different expert reviews running together, such as accessibility, data integrity, or interaction design. Fast vs full audits Fast audits provide quick issue scans for early iteration. Full audits dig deeper with alternatives and higher coverage for pre-share polish. # Fast audit for quick checks report = widget.audit(level=&quot;fast&quot;, display=False) # Full audit for deeper review full_report = widget.audit(level=&quot;full&quot;, reuse=True, display=False) Audit outputs are stored in .vibewidget/audits as JSON and YAML. How to use auditing You can run audits from Python to get a structured report without needing to run the widget UI. # Run a fast audit and return a report report = widget.audit(level=&quot;fast&quot;, display=False) # Deep audit for detailed alternatives full_report = widget.audit(level=&quot;full&quot;, reuse=True, display=False) In the UI, audit recommendations can be surfaced as a checklist inside the Edit Code view. You can then turn a specific concern into an edit request or keep it as a TODO for later. Audit in the UI (video) Watch a quick walkthrough of running audits inside the widget editor: Audit walkthrough on YouTube


# Reactivity
URL: https://vibewidget.dev/docs/reactivity
Connect widgets with reactive inputs and outputs.
Vibe Widgets stay synchronized with Python through a simple reactivity model. This page explains how data flows between your notebook and your widgets and how to wire widgets together. The three primitives PrimitiveDirectionPersistenceUse forInputPython → JSState (sticky)Data, configuration, selections from other widgetsOutputJS → PythonState (sticky)User selections, computed values, filtersActionPython → JSEvent (fire-once)Commands like reset, focus, export Inputs Inputs are values that flow into your widget from Python. Use them for anything the widget needs to display or respond to. Inputs are persistent: the widget holds onto the value until you change it. # Set an input from Python widget.inputs.threshold = 0.5 widget.inputs.data = new_df # resets the data in the widget You can also wire one widget&#x27;s output to another widget&#x27;s input: Widget PreviewOpen the live docs to see this interactive widget. # Slider selection flows into chart&#x27;s highlight chart = vw.create( &quot;scatter plot with brush selection&quot;, df, outputs=vw.outputs(selected_indices=&quot;indices of selected points&quot;) ) histogram = vw.create( &quot;histogram with highlighted bars for selected data&quot;, vw.inputs(df, selected_indices=chart.outputs.selected_indices) ) Outputs Outputs are values that flow out of your widget to Python. Use them for anything the widget produces that Python might care about. Like inputs, outputs are persistent state. # Read the current selection print(widget.outputs.selected_indices.value) # React to changes def on_selection(change): print(f&quot;Selection changed: {change.new}&quot;) widget.outputs.selected_indices.observe(on_selection) Actions Actions are one-time commands from Python to the widget. Use them for behavior that should happen once, not persist as state. Widget PreviewOpen the live docs to see this interactive widget. widget = vw.create( &quot;interactive scatter plot&quot;, df, actions=vw.actions(reset_view=&quot;Reset zoom and pan&quot;) ) widget.actions.reset_view() After an action fires, it&#x27;s done. The widget doesn&#x27;t &quot;remember&quot; that it was reset. Choosing the right primitive Ask yourself: should this value stick around? Yes → Input or Output. Use input if the value comes from Python; use output if it comes from the widget. No → Action. Use an action if it&#x27;s a one-time command. If you try to model a one-time command as an input, it becomes sticky: # Avoid this widget.inputs.should_reset = True The widget would reset and keep resetting because the input is still true. Actions avoid that behavior by firing once and not lingering. Wiring widgets together The real power of this model shows up when you connect widgets: Widget PreviewOpen the live docs to see this interactive widget. scatter = vw.create( &quot;scatter plot with brush selection tool&quot;, df, outputs=vw.outputs(selected_indices=&quot;indices of selected points&quot;) ) histogram = vw.create( &quot;histogram with highlighted bars for selected data&quot;, vw.inputs(df, selected_indices=scatter.outputs.selected_indices) ) When you select points in the scatter plot, the histogram updates via trait syncing without requiring any additional runs. Outputs are exposed under widget.outputs.&lt;name&gt;.


# Load & Save
URL: https://vibewidget.dev/docs/composability
Persist widgets to disk and reload them later.
Widgets can be saved to disk as portable bundles and reloaded later. This is useful for sharing, versioning, and avoiding re-generation. Save a widget Widget PreviewOpen the live docs to see this interactive widget. widget = vw.create(&quot;scatter plot with brush selection&quot;, df) widget.save(&quot;my_widget.vw&quot;) Save inputs alongside the widget: widget.save(&quot;my_widget_with_inputs.vw&quot;, include_inputs=True) Load a widget loaded = vw.load(&quot;my_widget.vw&quot;) loaded By default, loading uses approval mode so you can review before running: loaded = vw.load(&quot;my_widget.vw&quot;, approval=True) To auto-run a trusted widget: loaded = vw.load(&quot;my_widget.vw&quot;, approval=False) What gets stored Bundles include the widget code, metadata, and output/input signatures. When you save with include_inputs=True, input values are embedded in the bundle for reproducible reloads. Security notes Loaded widgets can execute JavaScript in the notebook frontend. Keep approval=True for untrusted files and review code before running.


# Theming
URL: https://vibewidget.dev/docs/theming
Style widgets with natural-language design specs.
Themes are natural-language design specs that guide code generation. List available themes import vibe_widget as vw themes = vw.themes() themes vw.themes() pretty-prints a concise list in notebooks. To get the full dict, use dict(themes). Create a custom theme theme = vw.theme(&quot;like national geographic but greener&quot;) # Inspect or reuse the generated description print(theme.description) vw.create(&quot;...&quot;, df, theme=theme.description) Use a theme in create vw.create(&quot;...&quot;, df, theme=&quot;financial_times&quot;) Iterate with themes Edits reuse the existing theme by default, so your visual language stays consistent as you refine behavior or layout. Widget PreviewOpen the live docs to see this interactive widget. v1 = vw.create(&quot;basic scatter&quot;, df, theme=&quot;financial_times&quot;) Widget PreviewOpen the live docs to see this interactive widget. v2 = v1.edit(&quot;add hover tooltips and a right-side legend&quot;) You can override the theme on an edit when you want a new look: v3 = v2.edit(&quot;soften the palette and reduce gridlines&quot;, theme=&quot;paper_white&quot;)


# Widgetarium
URL: https://vibewidget.dev/docs/widgetarium
The ecosystem of widgets and templates.
This documentation section is under construction.
