Observable Inputs

Notebooks

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:

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 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 ›

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

Toggle

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

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

Checkbox

Choose any from a set. API Reference ›

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

Radio

Choose one from a set. API Reference ›

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

Range

Pick a number. API Reference ›

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

Select

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

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

Text

Enter freeform single-line text. API Reference ›

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

Textarea

Enter freeform multi-line text. API Reference ›

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

Date

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

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

Color

Choose a color. API Reference ›

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

File

Choose a local file. API Reference ›

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

Search

Query a tabular dataset. Examples › API Reference ›

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:

viewof rows = Inputs.table(search)

Advanced & community inputs

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

• Form - combine multiple inputs for a compact display
• Synchronized inputs - bind two or more inputs
• Introduction to Views - more on Observable’s viewof

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

Name	Author	Description
2D Slider	Fabian Iwan	a two-dimensional range]
Binary Input	Ricky Reusser	bitwise IEEE floating point
DIY inputs	Bartosz Prusinowski	inputs with fun, custom styles
FineRange	Ricky Reusser	high-precision numeric control
Form Input	Mike Bostock	multiple inputs in single cell
Inputs	Jeremy Ashkenas	the original
Player	oscar6echo	detailed timing control for animation
Scrubber	Mike Bostock	play/pause/scrub control for animation
Range Slider	Fabian Iwand	a two-ended range
Ternary Slider	Yuri Vishnevsky	a proportion of three values
Data driven range sliders	David B.	a range input with a histogram
Snapping Histogram Slider	Robert Harris	a range input with a histogram
Inputs in grid	David B.	combine multiple inputs into a compact grid
List Input	Harris L.	enter more than one of something
Copier	Mike Bostock	a button to copy to the clipboard
Tangle	Mike Bostock	Bret Victor-inspired inline scrubbable numbers
Editor	CMU Data Interaction Group	code editor with syntax highlighting
Color Scheme Picker	Zack Ciminera	pick a D3 color scheme
Easing Curve Editor	Nhogs	create a custom easing curve