ipyvuetify

Warnings

• breaking ipyvuetify's API conventions differ significantly from standard ipywidgets and direct Vuetify HTML. Component names are CamelCase with 'v-' stripped (e.g., `v.Btn` for `<v-btn>`). Attributes are snake_case (e.g., `offset_y` for `offset-y`). Child components and text are passed via the `children` traitlet, and event listeners are set using the `.on_event(event_name, callback)` method. CSS `class` and `style` attributes require an underscore suffix (`class_`, `style_`).
  Fix: Always refer to the ipyvuetify documentation's 'Usage' section or translate directly from Vuetify documentation by applying ipyvuetify's specific naming and API conventions.
• gotcha In-place mutations of list or dictionary traitlets (e.g., appending to `my_list_traitlet.append('item')`) are not detected by ipywidgets' change notification system, which ipyvuetify relies upon. This means the frontend widget will not update.
  Fix: To update list or dictionary traitlets, always assign a *new* list or dictionary object. For example, `my_widget.items = my_widget.items + ['New Item']` or `my_widget.items = [*my_widget.items, 'New Item']`.
• gotcha The `value` attribute on ipyvuetify widgets is primarily for *setting* an initial value and does not reflect user interactions or two-way data binding. For interactive components where the user's input needs to be read, use the `v_model` attribute instead.
  Fix: Initialize interactive components with `v_model` (e.g., `v.Slider(v_model=25)`), and read the current state from `widget.v_model`.
• breaking ipyvuetify 3.0.0a2 and subsequent 3.x alpha releases are unstable, based on Vue 3.x, and primarily for future Solara 3.0 integration. They may have significant visual and functional breakage (e.g., issues with Vuetify2 appearance) and are not recommended for general use with ipyvuetify 1.x-based applications.
  Fix: For stable applications, strictly pin to `ipyvuetify<3.0.0` (i.e., use versions in the 1.x series).
• gotcha For users of JupyterLab, a separate JupyterLab extension must be installed (`jupyter labextension install jupyter-vuetify`) in addition to the pip package for ipyvuetify widgets to render correctly.
  Fix: Run `jupyter labextension install jupyter-vuetify` in your terminal where JupyterLab is installed.
• gotcha In Google Colab environments, `ipyvuetify` widgets may fail to render with an 'Unknown dependency jupyter-vue' error due to how Colab handles widget dependencies. This typically requires specific workarounds involving ensuring the `jupyter-vue` module is explicitly loaded.
  Fix: Consult specific Colab-related issues on the `ipyvuetify` GitHub or Colab documentation for current workarounds, often involving programmatic loading of `jupyter-vue`.
• gotcha The `v.FileUpload` widget has been reported to cause kernel crashes (`Kernel died`) when used with `ipykernel` versions greater than 6.29.
  Fix: Downgrade `ipykernel` to version <= 6.29 if using `v.FileUpload`, or avoid using the `v.FileUpload` widget until a fix is released.

Install

• pip install ipyvuetify PyPI
• jupyter labextension install jupyter-vuetify JupyterLab Extension (required for JupyterLab)

Imports

• v
  wrong:

  import ipyvuetify

  correct:

  import ipyvuetify as v

  The common convention is to import ipyvuetify as 'v' for brevity, similar to 'np' for NumPy.
• Btn
  wrong:

  v.v_btn() or v.button()

  correct:

  v.Btn()

  Vuetify component names (e.g., `<v-btn>`) are translated to Python as CamelCase classes with the 'v-' prefix stripped (e.g., `v.Btn`).

Quickstart

This quickstart demonstrates creating a button and a text field, attaching an event listener to the button, and updating the text field's value using the `v_model` attribute. It showcases basic widget creation, event handling, and displaying components in a Jupyter environment.

import ipyvuetify as v
from IPython.display import display

# Create a text field to display messages
message_output = v.TextField(label="Message", readonly=True, v_model="Click the button!")

# Define a callback function for the button click
def on_button_click(widget, event, data):
    message_output.v_model = "Button was clicked!"

# Create a button and attach the event listener
button = v.Btn(children=["Click Me"])
button.on_event('click', on_button_click)

# Display the widgets within a container
display(v.Container(children=[button, message_output]))