Skip to content

Observable Inputs

NotebooksLearn about notebooks vs. projects

These lightweight interface components—buttons, sliders, dropdowns, tables, and the like—help you explore data and build interactive displays. For a walkthrough of how you might use these to support data analysis in a notebook, see Hello, Inputs!.

Note

This document describes the syntax used in Observable notebooks. It is different from projects using Observable Framework.

Usage

Declare your inputs with viewof, like so:

js
viewof gain = Inputs.range([0, 11], {value: 5, step: 0.1, label: "Gain"})

The range input above (created with Inputs.range()) specifies the total range of values a user can choose from (0 to 11), along with options for:

  • value: the default starting value or option of an input
  • step: the increments along the range (here, change by increments of 0.1)
  • label: a label informing or prompting the user
A JavaScript cell containing code to create a range slider input, using viewof to both view the widget in the notebook and store the value for use elsewhere. The code shown to make the input is: viewof gain = Inputs.range([0, 11], {value: 5, step: 0.1, label: “Gain”})
A range slider created with Inputs.range.

Now you can reference the input's value (here gain) in any cell, and the cell will run whenever the input changes. No event listeners required!

To quickly create an input, open the add cell menu by clicking the plus sign in the left margin, then search for an input by name (or search for "input" to see all built-in input options). Click on the desired input, and a new JavaScript cell is added containing placeholder code that you can update to create your input.

Observable Inputs are released under the ISC license and depend only on Hypertext Literal, our tagged template literal for safely generating dynamic HTML. If you are interested in contributing or wish to report an issue, please see our repository. For recent changes, please see our release notes.

Basics

These basic inputs will get you started:

  • Button: do something when a button is clicked
  • Toggle: toggle between two values (on or off)
  • Checkbox: choose any from a set
  • Radio: choose one from a set
  • Range or Number: choose a number in a range (slider)
  • Select: choose one or any from a set (drop-down menu)
  • Text: enter freeform single-line text
  • Textarea: enter freeform multi-line text
  • Date or Datetime: choose a date
  • Color: choose a color
  • File: choose a local file

Minimal examples of each are shown below. Click on the input name and links for examples to explore and interact with in Observable notebooks.

Button

Do something when a button is clicked. API Reference ›

js
viewof clicks = Inputs.button("Click me")

Toggle

Toggle between two values (on or off). API Reference ›

js
viewof mute = Inputs.toggle({label: "Mute"})

Checkbox

Choose any from a set. API Reference ›

js
viewof flavors = Inputs.checkbox(["salty", "sweet", "bitter", "sour", "umami"], {label: "Flavors"})

Radio

Choose one from a set. API Reference ›

js
viewof flavor = Inputs.radio(["salty", "sweet", "bitter", "sour", "umami"], {label: "Flavor"})

Range

Pick a number. API Reference ›

js
viewof n = Inputs.range([0, 255], {step: 1, label: "Favorite number"})

Select

Choose one, or any, from a menu. API Reference ›

js
viewof homeState = Inputs.select([null].concat(stateNames), {label: "Home state"})

Text

Enter freeform single-line text. API Reference ›

js
viewof name = Inputs.text({label: "Name", placeholder: "What’s your name?"})

Textarea

Enter freeform multi-line text. API Reference ›

js
viewof bio = Inputs.textarea({label: "Biography", placeholder: "What’s your story?"})

Date

Choose a date, or a date and time. API Reference ›

js
viewof birthday = Inputs.date({label: "Birthday"})

Color

Choose a color. API Reference ›

js
viewof color = Inputs.color({label: "Favorite color", value: "#4682b4"})

File

Choose a local file. API Reference ›

js
viewof file = Inputs.file({label: "CSV file", accept: ".csv", required: true})

Inputs for tabular data

These inputs are designed to work with tabular data such as CSV or TSV file attachments and database clients.

  • Search - query a tabular dataset
  • Table - browse a tabular dataset

Query a tabular dataset. Examples › API Reference ›

js
viewof search = Inputs.search(capitals, {placeholder: "Search U.S. capitals"})

Table

Browse a tabular dataset. Examples › API Reference ›

For an array of objects named search:

js
viewof rows = Inputs.table(search)

Advanced & community inputs

Got the basics? Here are a few more advanced techniques:

For even more, consider these "friends & family" inputs and techniques shared by the Observable community:

NameAuthorDescription
2D SliderFabian Iwana two-dimensional range]
Binary InputRicky Reusserbitwise IEEE floating point
DIY inputsBartosz Prusinowskiinputs with fun, custom styles
FineRangeRicky Reusserhigh-precision numeric control
Form InputMike Bostockmultiple inputs in single cell
InputsJeremy Ashkenasthe original
Playeroscar6echodetailed timing control for animation
ScrubberMike Bostockplay/pause/scrub control for animation
Range SliderFabian Iwanda two-ended range
Ternary SliderYuri Vishnevskya proportion of three values
Data driven range slidersDavid B.a range input with a histogram
Snapping Histogram SliderRobert Harrisa range input with a histogram
Inputs in gridDavid B.combine multiple inputs into a compact grid
List InputHarris L.enter more than one of something
CopierMike Bostocka button to copy to the clipboard
TangleMike BostockBret Victor-inspired inline scrubbable numbers
EditorCMU Data Interaction Groupcode editor with syntax highlighting
Color Scheme PickerZack Ciminerapick a D3 color scheme
Easing Curve EditorNhogscreate a custom easing curve