Inputs

Inputs allow you to pass data into your Widget at runtime. They are accessed in the Widget Designer using the useInputs hook:

import { useInputs } from "~lib/use-inputs";

const { MY_INPUT, API_KEY } = useInputs();

The Inputs dialog has three tabs: Public Inputs, Private Inputs, and Integrations.

info

Input names must be alphanumeric with underscores only (valid JavaScript variable names).

tip

It is good practice to name your inputs in ALL_CAPS_SNAKE_CASE to indicate that they are constants.

Public Inputs

Public Inputs are the customization options exposed to users installing your Widget. They allow end users to configure your Widget to their needs without modifying any code.

info

Public Inputs are set by users installing the Widget, not by the author.

Creating an Input

Click Create new input to add a new input. Each input has the following properties:

Property	Description
Name	The variable name used in code. Must be a valid JavaScript variable name (alphanumeric and underscores).
Description	A user-friendly label explaining what this input does.
Type	The kind of input field presented to the user (see Input Types below).
Required	Whether the user must provide a value before using the Widget.

Testing

You can specify a test value for each input to simulate how your Widget behaves when a user provides a value. If no test value is set, a default value is used instead.

Input Types

Different input types help users configure your Widget more effectively.

String

A free-form text field.

Example use cases: city name, ticker symbol, JSON configuration.

Sensitive

A text field that hides what is typed, like a password field.

Example use cases: the user's own API key or access token.

For a secret of your own that users should never see, use a Private Input instead.

Number

A numeric input field.

Select

A dropdown list where the user can pick one value from a predefined set of options.

Example use cases: currency, news source, chart type.

Multi-select

A dropdown list where the user can pick multiple values from a predefined set of options.

Date

A date picker for the user to select a date.

Time Zone

A time zone selector.

Address

An address picker.

Icon

An icon picker. Draw the icon the user picks with Icon, passing the input's value through inputIconName:

import { Icon, inputIconName } from "~lib/icon";
import { useInputs } from "~lib/use-inputs";

export const Widget = () => {
  const { icon } = useInputs();
  const name = inputIconName(icon);
  return name ? <Icon name={name} size={64} /> : null;
};

---

Private Inputs

Private Inputs are encrypted secrets that are only accessible by the Widget author. They are used for sensitive data such as API keys, passwords, and tokens.

info

Private Inputs are constant and can only be set by the author of the Widget. Users installing the Widget do not need to provide these.

How They Work

• Enter a key (name) and value to create a secret.
• Once saved, the value is encrypted and displayed as masked dots. It cannot be viewed again by anyone, including you.
• To change a value, delete the secret and re-create it.
• Private Inputs are accessed using the same useInputs() hook as Public Inputs.

warning

When a Widget is forked, Private Inputs are not copied over. The new author must enter their own values.

---

Integrations

Integrations allow your Widget to connect to third-party services using OAuth 2.0. This enables secure authentication with external APIs without exposing credentials to end users.

Setting Up an Integration

Click New Integration to configure an OAuth connection. You will need the following from your OAuth provider:

Field	Description
Name	A display name for this integration.
Client ID	The OAuth application client ID from your provider.
Client Secret	The OAuth application client secret. Stored securely and never displayed.
Authorization Endpoint	The provider's /authorize URL.
Token Endpoint	The provider's /token URL.
Scopes	Comma-separated list of OAuth scopes to request.

Redirect URI

When configuring your OAuth application with a provider (e.g. Google, GitHub, Spotify), you must set the Redirect URI (also called "Callback URL") to:

https://console.blotch.app/oauth/callback

You can also copy it from the Redirect URI box in the integration form.

This is because after a user authorizes access, the OAuth provider redirects the browser back to this URL with an authorization code. Blotch captures this code and exchanges it for access and refresh tokens. If the redirect URI does not match exactly, the OAuth provider will reject the authorization request.

warning

The redirect URI must match exactly what you register with your OAuth provider — including the protocol (https) and path. No trailing slash.

Advanced Settings

These fields have sensible defaults but can be customized if your OAuth provider uses non-standard parameter names:

Field	Default	Description
Code Token Name	code	The parameter name for the authorization code.
Access Token Name	access_token	The parameter name for the access token.
Refresh Token Name	refresh_token	The parameter name for the refresh token.
Extra Params	(empty)	Additional query parameters to include in the OAuth request.

Connection Status

Each integration shows its connection status:

• Connected - The OAuth flow has been completed and tokens are stored.
• Not Connected - The OAuth flow has not been completed yet. Click Connect to initiate it.