Inputs

Input Cell

The Input Cell lets you capture interactive input from viewers of your document or app. These inputs can be referenced in other cells (Python, SQL, Prompt, etc.) to create dynamic, data-driven workflows.

You can choose between eight input types:

1. Text - Accepts freeform text input
2. Number - Accepts numeric input with optional constraints
3. Slider - Allows selection of a number within a range
4. Date - Lets the user select a date (and optionally, time)
5. Dropdown - Single selection from a list of options
6. Checkbox - Simple on/off toggle
7. Multiselect - Multiple selections from a list of options
8. Button - Click trigger for user-initiated actions

Adding an Input Cell

1. Click the + Add Cell button or press / to open the cell menu.
2. Select Input from the list of cell types.
3. Choose your input type from the dropdown in the cell settings.
4. Configure the settings for your chosen input type.
5. Give your input a descriptive Label so viewers know what it controls.

Input Types

Text

Accepts freeform text input from the user. Great for names, search terms, notes, or any text-based input.

Settings:

• Multiline (optional) - Enable to allow multiple lines of text. Useful for longer responses like comments or descriptions.

Example uses:

• Search filters
• Customer names
• Comments or notes
• Custom prompts for AI cells

Number

Accepts numeric input. Use this when you need a specific number from the user.

Settings:

• Min (optional) - Minimum allowed value
• Max (optional) - Maximum allowed value
• Increment size (optional) - Step amount for the +/- buttons

Example uses:

• Row limits for queries
• Budget amounts
• Quantity inputs
• Year or age values

Slider

Allows users to select a number by dragging a slider. Best for selecting values within a known range where approximate selection is acceptable.

Settings:

• Min (required) - Minimum value of the slider
• Max (required) - Maximum value of the slider
• Step size (optional) - Increment between allowed values (e.g., 5 for 0, 5, 10, 15…)

Example uses:

• Percentage adjustments (0-100)
• Model hyperparameters
• Date range spans (last N days)
• Confidence thresholds

Date

Lets the user select a date from a calendar picker.

Settings:

• Include time (optional) - Enable to also capture hours and minutes along with the date.

Example uses:

• Report date ranges
• Scheduling events
• Filtering data by date
• Setting deadlines

Dropdown

Allows users to select a single option from a list. Use when you have a predefined set of valid choices.

Settings:

• Options source (required) - Where the dropdown options come from (see Dynamic Options below)
• Allow none (optional) - Enable to let users clear their selection
• Placeholder (optional) - Text shown when no option is selected

Example uses:

• Selecting a department or region
• Choosing a chart type
• Picking a date range preset (Last 7 days, Last 30 days, etc.)
• Selecting a customer from a list

Checkbox

A simple on/off toggle. Returns "True" when checked, "False" when unchecked.

Note: The values are strings, not boolean values. In Python, compare with == "True" rather than using the value directly as a boolean.

Example uses:

• Include/exclude filters
• Feature toggles
• Show/hide options
• Agree to terms

Example in Python:

if input_1 == "True":
    df = df_all
else:
    df = df_all.filter(pl.col("archived") == False)

Multiselect

Allows users to select multiple options from a list. The value is returned as a JSON array string.

Settings:

• Options source (required) - Where the options come from (see Dynamic Options below)

Example value: When a user selects “Sales” and “Marketing”, the input value is ["Sales", "Marketing"] (as a JSON string).

Example uses:

• Selecting multiple departments to include
• Choosing several products to compare
• Filtering by multiple categories
• Selecting team members

Example in Python:

# input_1 is already a list when using multiselect
# Result: ["Sales", "Marketing"]

# Filter dataframe to selected departments
df_filtered = df.filter(pl.col("department").is_in(input_1))

Example in SQL:

-- Use the multiselect value in a WHERE IN clause
SELECT * FROM employees
WHERE department IN ({{input_1}})

Button

A click trigger for user-initiated actions. Unlike other inputs, a Button only yields "True" at the moment it is clicked. After downstream cells finish running, the button resets.

This makes buttons ideal for actions that should only happen on demand, not automatically when the document loads.

Settings:

• Button label (optional) - Text displayed on the button (e.g., “Send Email”, “Generate Report”)
• Button style (optional):
  • secondary (default) - Outlined button style
  • danger - Red button for destructive or irreversible actions

Example uses:

• Sending emails or notifications
• Triggering expensive API calls
• Running long computations
• Exporting data
• Deleting records (use danger style)
• Refreshing external data

How it works:

1. User clicks the button
2. Button value becomes "True"
3. Downstream cells that reference the button run
4. Button resets (value is no longer "True")

Example in Python:

# This code only runs when the button is clicked
if input_1 == "True":
    send_notification_email(report_data)
    print("Email sent successfully!")

Tip: Use the danger style for buttons that perform destructive actions like deleting data or sending irreversible notifications. This provides a visual warning to users.

Referencing Input Values

Each input cell has a variable name shown below it (e.g., input_1, input_2). You can rename these to something more descriptive.

In SQL Cells

Use Jinja templating with double curly braces:

SELECT * FROM orders
WHERE region = '{{region_dropdown}}'
  AND order_date >= '{{start_date}}'
LIMIT {{row_limit}}

In Python Cells

Input values are available as variables directly:

# Use input values directly (they are strings)
row_limit = int(input_1)

# Use in your code
filtered_df = df.filter(pl.col("region") == input_2).head(row_limit)

In Prompt Cells (AI)

Use Jinja templating just like in SQL:

Analyze the sales data for {{region_dropdown}} and provide insights
about trends over the last {{time_range}} days.

In Text Cells

Insert dynamic values into your narrative:

The report shows {{row_count}} orders from the {{region_dropdown}} region,
with a total value of ${{total_value}}.

Dynamic Options for Dropdown and Multiselect

Dropdown and Multiselect inputs can get their options from a Python variable, making them dynamic based on your data.

Setting Up Dynamic Options

1. Create a Python cell that defines a list variable:

# Fetch unique departments from your data
departments = df["department"].unique().to_list()
# Result: ["Sales", "Marketing", "Engineering", "Support"]

2. In your Dropdown or Multiselect settings, set the Options source to the variable name (e.g., departments).

3. The input will now show options from that list, and update automatically when the list changes.

Example: Dynamic Region Filter

# Python cell: Get unique regions from data
regions = df["region"].unique().sort().to_list()

Then create a Dropdown input with regions as the options source. Now your dropdown will always show the current regions in your data.

Example Use Cases

Dynamic Dashboard Filters

Use a date input and dropdown to filter SQL queries:

SELECT * FROM orders
WHERE order_date >= '{{start_date}}'
  AND region = '{{region_dropdown}}'
ORDER BY order_date DESC

Parameterizing Machine Learning Models

Use a slider to control model hyperparameters:

n_clusters = int(input_1)

from sklearn.cluster import KMeans
model = KMeans(n_clusters=n_clusters)
model.fit(data)

Interactive AI Prompts

Use text inputs to customize AI analysis:

User wants to know: {{user_question}}

Analyze the dataset focusing on the {{selected_metric}} metric
and provide actionable insights for the {{department}} team.

What-If Analysis

Use number inputs to adjust projections:

growth_rate = float(input_1) / 100
current_revenue = 1000000

projected_revenue = current_revenue * (1 + growth_rate)
print(f"Projected revenue: ${projected_revenue:,.2f}")

User-Triggered Actions with Buttons

Use a button to send a report only when requested:

if input_1 == "True":
    # Generate and send the report
    report = generate_report(df)
    send_email(
        to="team@company.com",
        subject="Weekly Sales Report",
        body=report
    )
    print("Report sent!")
else:
    print("Click the button above to send the report.")

Tip: Combine multiple input types to create powerful interactive applications. For example, use dropdowns for category selection, date pickers for time ranges, and a button to trigger the final export or notification.