Settings components

Components for building plugin settings panels

Settings components provide pre-built UI elements for creating configuration interfaces in BetterDiscord plugins. These components handle state management, validation, and styling automatically.

ColorInput

A color picker component with a custom color selector and optional color swatches.

value · string | number · required

Current color value as hex string (e.g., "#ff0000") or number (e.g., 16711680)

onChange · function

Callback function called when the color changes. Receives the new color value as a string.

colors · Array<string | number>

Array of preset colors to display as swatches. Defaults to Discord’s default color palette.

defaultValue · string | number

Default color value. When provided, shows a default color button.

disabled · boolean · default: "false"

Whether the color picker is disabled

Usage

const {ColorInput} = BdApi.Components;

function MySettings() {
    const [color, setColor] = React.useState("#5865f2");

    return (
        <ColorInput
            value={color}
            onChange={setColor}
            defaultValue="#5865f2"
            colors={["#5865f2", "#57f287", "#fee75c", "#ed4245"]}
        />
    );
}

DropdownInput

A dropdown select menu with custom styling.

value · any

Currently selected value

options · Array<SelectOption> · required

Array of option objects. Each option should have:

• value (any): The option’s value
• label (string): Display text
• id (string, optional): Unique identifier

onChange · function

Callback function called when selection changes. Receives the new value.

style · 'transparent' | 'default'

Visual style of the dropdown

disabled · boolean · default: "false"

Whether the dropdown is disabled

Usage

const {DropdownInput} = BdApi.Components;

function MySettings() {
    const [theme, setTheme] = React.useState("dark");

    const options = [
        {value: "dark", label: "Dark"},
        {value: "light", label: "Light"},
        {value: "amoled", label: "AMOLED"}
    ];

    return (
        <DropdownInput
            value={theme}
            options={options}
            onChange={setTheme}
        />
    );
}

KeybindInput

A keybind recorder that captures keyboard input.

value · string[] · required

Array of key names representing the current keybind (e.g., ["Control", "Shift", "K"])

onChange · function

Callback function called when the keybind changes. Receives the new key array.

max · number · default: "4"

Maximum number of keys allowed in the keybind

clearable · boolean · default: "false"

Whether to show a clear button

disabled · boolean · default: "false"

Whether the keybind input is disabled

Usage

const {KeybindInput} = BdApi.Components;

function MySettings() {
    const [keybind, setKeybind] = React.useState(["Control", "K"]);

    return (
        <KeybindInput
            value={keybind}
            onChange={setKeybind}
            max={3}
            clearable
        />
    );
}

NumberInput

A number input with increment and decrement buttons.

value · number | string · required

Current numeric value

onChange · function

Callback function called when the value changes. Receives the new value.

min · number

Minimum allowed value

max · number

Maximum allowed value

step · number · default: "1"

Amount to increment/decrement by

disabled · boolean · default: "false"

Whether the input is disabled

Usage

const {NumberInput} = BdApi.Components;

function MySettings() {
    const [count, setCount] = React.useState(50);

    return (
        <NumberInput
            value={count}
            onChange={setCount}
            min={0}
            max={100}
            step={5}
        />
    );
}

RadioInput

A radio button group for selecting one option from multiple choices.

value · any · required

Currently selected value

options · Array<RadioOption> · required

Array of option objects. Each option should have:

• name (string): Display text
• value (any): The option’s value
• description (string, optional): Description text
• color (string, optional): Border color when selected

onChange · function

Callback function called when selection changes. Receives the new value.

name · string

Name attribute for the radio group

disabled · boolean · default: "false"

Whether the radio group is disabled

Usage

const {RadioInput} = BdApi.Components;

function MySettings() {
    const [mode, setMode] = React.useState("auto");

    const options = [
        {
            name: "Automatic",
            value: "auto",
            description: "Automatically detect the best mode"
        },
        {
            name: "Manual",
            value: "manual",
            description: "Manually configure settings",
            color: "#5865f2"
        },
        {
            name: "Disabled",
            value: "disabled",
            description: "Turn off this feature"
        }
    ];

    return (
        <RadioInput
            name="mode-select"
            value={mode}
            options={options}
            onChange={setMode}
        />
    );
}

SearchInput

A search input field with clear functionality.

onChange · function

Callback function called when the input value changes. Receives a change event.

placeholder · string

Placeholder text for the input

className · string

Additional CSS classes to apply

onKeyDown · function

Callback function for keyboard events

Usage

const {SearchInput} = BdApi.Components;

function MyList() {
    const [searchTerm, setSearchTerm] = React.useState("");

    return (
        <SearchInput
            placeholder="Search items..."
            onChange={(e) => setSearchTerm(e.target.value)}
        />
    );
}

SliderInput

A slider component with optional markers and unit display.

value · number | string · required

Current slider value

min · number · required

Minimum value

max · number · required

Maximum value

onChange · function

Callback function called when the value changes. Receives the new value.

step · number

Step increment for the slider

units · string · default: "''"

Unit suffix to display (e.g., "%", "px", "ms")

markers · Array<number | SliderMarker>

Array of marker positions. Can be numbers or objects with:

• value (number): Position on the slider
• label (string): Label to display

disabled · boolean · default: "false"

Whether the slider is disabled

Usage

const {SliderInput} = BdApi.Components;

function MySettings() {
    const [volume, setVolume] = React.useState(75);

    return (
        <SliderInput
            value={volume}
            min={0}
            max={100}
            onChange={setVolume}
            units="%"
            markers={[0, 25, 50, 75, 100]}
        />
    );
}

With custom marker labels:

const markers = [
    {value: 0, label: "Off"},
    {value: 50, label: "Medium"},
    {value: 100, label: "Max"}
];

<SliderInput
    value={intensity}
    min={0}
    max={100}
    onChange={setIntensity}
    markers={markers}
/>

SwitchInput

A toggle switch component.

value · boolean · required

Current switch state

onChange · function

Callback function called when the switch is toggled. Receives the new boolean value.

id · string

HTML id attribute for the input element

disabled · boolean · default: "false"

Whether the switch is disabled

internalState · boolean · default: "true"

Whether to manage state internally

Usage

const {SwitchInput} = BdApi.Components;

function MySettings() {
    const [enabled, setEnabled] = React.useState(false);

    return (
        <SwitchInput
            id="enable-feature"
            value={enabled}
            onChange={setEnabled}
        />
    );
}

TextInput

A text input field component.

value · string · required

Current input value

onChange · function

Callback function called when the input changes. Receives the new string value.

placeholder · string

Placeholder text for the input

maxLength · number

Maximum number of characters allowed

disabled · boolean · default: "false"

Whether the input is disabled

onKeyDown · function

Callback function for keyboard events

Usage

const {TextInput} = BdApi.Components;

function MySettings() {
    const [name, setName] = React.useState("");

    return (
        <TextInput
            value={name}
            onChange={setName}
            placeholder="Enter your name..."
            maxLength={50}
        />
    );
}

SettingItem

A container component for individual settings that provides consistent layout with labels and descriptions.

id · string · required

Unique identifier for the setting

name · string

Label text for the setting

note · string

Description or help text displayed below the setting

inline · boolean · default: "false"

Whether to display the control inline with the label (recommended for switches)

children · ReactNode

The setting control component (e.g., SwitchInput, SliderInput)

Usage

const {SettingItem, SwitchInput, SliderInput} = BdApi.Components;

function MySettings() {
    const [enabled, setEnabled] = React.useState(false);
    const [opacity, setOpacity] = React.useState(80);

    return (
        <div>
            <SettingItem
                id="enable-overlay"
                name="Enable overlay"
                note="Shows an overlay on the screen"
                inline
            >
                <SwitchInput value={enabled} onChange={setEnabled} />
            </SettingItem>

            <SettingItem
                id="overlay-opacity"
                name="Overlay opacity"
                note="Adjust the transparency of the overlay"
            >
                <SliderInput
                    value={opacity}
                    min={0}
                    max={100}
                    onChange={setOpacity}
                    units="%"
                />
            </SettingItem>
        </div>
    );
}

SettingGroup

A collapsible group container for organizing multiple related settings.

id · string · required

Unique identifier for the group

name · string

Display name for the group header

settings · Array<Setting> · required

Array of setting configuration objects. Each setting should have:

• id (string): Unique identifier
• name (string): Display name
• note (string): Description
• type (string): Component type ("switch", "slider", "text", "dropdown", "number", "radio", "keybind", "color", "button", "custom")
• value (any): Current value
• onChange (function): Change handler
• Additional props specific to the component type

collapsible · boolean · default: "false"

Whether the group can be collapsed

shown · boolean

Whether the group is initially expanded (for collapsible groups)

onChange · function

Callback function called when any setting changes. Receives (id, settingId, value) or (settingId, value) depending on whether a group id is provided.

showDivider · boolean · default: "false"

Whether to show a divider after the group

collection · string

Collection name for integration with BetterDiscord’s settings store

onDrawerToggle · function

Callback function called when the group is expanded or collapsed

children · ReactNode

Additional custom content to render in the group

Usage

const {SettingGroup} = BdApi.Components;

function MySettings() {
    const handleChange = (settingId, value) => {
        console.log(`Setting ${settingId} changed to:`, value);
        // Save to your plugin's config
    };

    const generalSettings = [
        {
            type: "switch",
            id: "enabled",
            name: "Enable plugin",
            note: "Turns the plugin on or off",
            value: true,
            onChange: (value) => console.log('Enabled:', value)
        },
        {
            type: "slider",
            id: "intensity",
            name: "Effect intensity",
            note: "Controls how strong the effect is",
            value: 50,
            min: 0,
            max: 100,
            units: "%",
            onChange: (value) => console.log('Intensity:', value)
        }
    ];

    const advancedSettings = [
        {
            type: "keybind",
            id: "hotkey",
            name: "Toggle hotkey",
            note: "Keyboard shortcut to toggle the plugin",
            value: ["Control", "Shift", "T"],
            clearable: true,
            onChange: (value) => console.log('Hotkey:', value)
        },
        {
            type: "color",
            id: "accent",
            name: "Accent color",
            note: "Choose your preferred accent color",
            value: "#5865f2",
            defaultValue: "#5865f2",
            onChange: (value) => console.log('Color:', value)
        }
    ];

    return (
        <div>
            <SettingGroup
                id="general"
                name="General Settings"
                settings={generalSettings}
                onChange={handleChange}
            />

            <SettingGroup
                id="advanced"
                name="Advanced Settings"
                settings={advancedSettings}
                onChange={handleChange}
                collapsible
                shown={false}
            />
        </div>
    );
}