# 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.8+ and an OpenRouter API key. export OPENROUTER_API_KEY=&#x27;your-key&#x27; Quick start 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.2-codex&quot;) vw.config(mode=&quot;premium&quot;, model=&quot;openrouter&quot;) vw.config(execution=&quot;approve&quot;) API key setup export OPENROUTER_API_KEY=&#x27;your-key&#x27; 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) 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. import vibe_widget as vw widget = vw.create( &quot;bar chart of revenue by region&quot;, df ) widget Inputs and outputs Use vw.inputs to pass multiple inputs, and vw.outputs to define reactive state your widget exposes. vw.create( &quot;...&quot;, vw.inputs(df, selected_indices=other_widget.outputs.selected_indices) ) scatter = vw.create( &quot;scatter with brush selection&quot;, df, outputs=vw.outputs(selected_indices=&quot;indices of selected points&quot;) ) scatter.outputs.selected_indices.value Dataflow and I/O contract vw.create converts data to a list of record dicts and cleans non-JSON values (NaN/NaT/inf to None). Inputs and outputs are synced traitlets. When providing another widget output, Vibe Widget reads the current value once, then keeps it in sync via trait updates. Outputs start as None and are updated by generated JS code. Supported data sources pandas.DataFrame local file paths (CSV/TSV, JSON/GeoJSON, Parquet, NetCDF, XML, ISF, Excel, PDF, TXT) URLs (via crawl4ai, best-effort) Some loaders require optional dependencies (for example, xarray for NetCDF or camelot for PDF). Theming Themes are natural-language design specs that guide code generation. vw.create(&quot;...&quot;, df, theme=&quot;financial_times&quot;) vw.create(&quot;...&quot;, df, theme=&quot;like national geographic but greener&quot;) Built-in themes are listed via vw.themes(). Theme prompts are cached for the session and can be saved locally. 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.
While developing interactive widgets, we often do not know what to fully specify until after the first version exists. Vibe Widget makes iteration a first-class workflow by letting you edit generated widgets through code or the UI. Edits reuse existing code and optionally the theme, then apply requested changes. Each edit produces a new widget instance and persists a new version in the widget store. Python edits Use Python edits when you want structural changes, broader logic refactors, or to preserve edits as code in notebooks and scripts. Python edits are ideal for larger, explicit changes you want to keep versioned and reproducible. v1 = vw.create(&quot;basic scatter&quot;, df) # Large or structural changes v2 = v1.edit(&quot;add hover tooltips and a right-side legend&quot;) Component-level edits are ideal when the widget exposes named subcomponents and you want precise changes without rewriting the full widget. # Example: targeted edits via components v3 = v1.component.colo_legend.edit(&quot;style the legend with a muted palette&quot;, inputs=df) UI edits Use UI edits for fast, interactive iteration inside the widget runtime. These are best for targeted adjustments, quick fixes, and diagnostics without switching to code. Source code editing Make precise changes in the generated JS/HTML/CSS when you need direct control over logic or styling. Visual editing (Edit Element) Select a specific element by its bounding box and issue an edit scoped to that element, using full context from the widget. Auditing Detect issues, get recommendations, and optionally turn a concern into a fix request. See the Audit docs for more information.


# 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.


# Reactivity
URL: https://vibewidget.dev/docs/reactivity
Connect widgets with reactive inputs and outputs.
Outputs are reactive state handles that can be passed into other widgets. 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. Outputs are exposed under widget.outputs.&lt;name&gt;.


# Data Sources
URL: https://vibewidget.dev/docs/data-sources
Supported inputs and loaders.
This documentation section is under construction.


# Composability
URL: https://vibewidget.dev/docs/composability
Compose widgets using components and outputs.
This documentation section is under construction.


# 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 vw.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;)


# Cross-Widget Interactions
URL: https://vibewidget.dev/docs/examples/cross-widget
Interactive notebook example for cross-widget state sharing.
Interactive NotebookCross-Widget Interactions


# Tic-Tac-Toe AI
URL: https://vibewidget.dev/docs/examples/tictactoe
Interactive notebook example for game logic and UI.
Interactive NotebookTic-Tac-Toe AI


# PDF & Web Data Extraction
URL: https://vibewidget.dev/docs/examples/pdf-web
Interactive notebook example for scraping and parsing.
Interactive NotebookPDF &amp; Web Data Extraction


# Widget Editing
URL: https://vibewidget.dev/docs/examples/edit
Interactive notebook example for editing workflows.
Interactive NotebookWidget Editing


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