Built-in Controls

Installation

Install the widget controls along with the widget view infrastructure:

npx shadcn@latest add @nteract/widget-controls

Usage

Import the controls module to register all built-in widgets:

// Import to register all built-in widgets
import "@/components/widgets/controls"

// Or import specific widgets
import { IntSlider, Button, VBox } from "@/components/widgets/controls"

Widget Reference

Sliders

Common props: value, min, max, step, description, disabled, orientation, readout, readout_format FloatLogSlider props: base (default 10), value, min, max (exponents) Selection sliders: index, _options_labels, readout

Progress Bars

Common props: value, min, max, description, bar_style ("success", "info", "warning", "danger")

Text Input

Common props: value, description, placeholder, disabled, continuous_update

Numeric Input

Common props: value, min, max, step, description, disabled, continuous_update

Display

Label/HTML props: value, description, placeholder HTMLMath props: value (supports $...$ and $$...$$ math), description Image props: value (base64), format, width, height, description Audio/Video props: value (base64), format, autoplay, loop, controls

Boolean

Common props: value, description, disabled

Selection

Common props: index, _options_labels, description, disabled, rows Combobox props: value, options, placeholder, ensure_option, continuous_update

Other

Button props: description (button text), button_style, tooltip, disabled ColorPicker props: value (hex color), description, concise, disabled Valid props: value (boolean), readout (status message), description Play props: value, min, max, step, interval (ms), _playing, repeat DatePicker/TimePicker/Datetime props: value, min, max, description, disabled FileUpload props: value (file array), accept, multiple, button_style

Multi-value Inputs

Common props: value (array), description, allow_duplicates, placeholder TagsInput/ColorsInput: allowed_tags IntsInput/FloatsInput: min, max

Layout Containers

Common props: children (array of IPY_MODEL_<id> references), box_style Tab/Accordion/Stack props: _titles, selected_index

Gamepad Controller

Controller props: index, connected, name, mapping, buttons, axes, timestamp ControllerButton props: pressed (boolean), value (float 0-1) ControllerAxis props: value (float -1 to 1)

Customizing Widgets

Custom widget props

All widget components (built-in and custom) receive WidgetComponentProps:

interface WidgetComponentProps {
  modelId: string;    // The comm_id of the widget
  className?: string; // Optional CSS classes
}

Override a widget globally

Register your own component to replace any built-in widget:

import { registerWidget } from "@/components/widgets/widget-registry"
import { useWidgetModelValue, useWidgetStoreRequired } from "@/components/widgets/widget-store-context"

function MyFancySlider({ modelId, className }) {
  const { sendUpdate } = useWidgetStoreRequired()
  const value = useWidgetModelValue(modelId, "value") ?? 0

  return (
    <div className={className}>
      <input
        type="range"
        value={value}
        onChange={(e) => sendUpdate(modelId, { value: Number(e.target.value) })}
      />
    </div>
  )
}

// Replace the default IntSlider everywhere
registerWidget("IntSliderModel", MyFancySlider)

Style via CSS variables

All widgets use shadcn's CSS variable theming. Customize colors in your tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: "hsl(var(--primary))",
        // ... your custom theme
      }
    }
  }
}

Fork and modify

Copy any widget file from the controls/ directory and modify it directly. The widgets are intentionally simple and self-contained.