API

API

The Drag & Drop Card API is a local JavaScript API for controlling dashboard settings from custom cards, HTML/Web cards, browser scripts, or advanced Home Assistant dashboard logic.

The API is designed for controlling the Drag & Drop Card itself. It is not a cloud API, not a REST API, and not a replacement for Home Assistant services.

Current API version: 1

Access

You can access the API directly from the Drag & Drop Card element:

const card = document.querySelector('drag-and-drop-card');
const api = card.dashboardApi;
// alias:
const api2 = card.ddc;

Inside a card where you do not have direct access to the parent element, request the API with an event:

let api = null;

this.dispatchEvent(new CustomEvent('ddc-api-request', {
  bubbles: true,
  composed: true,
  detail: {
    receive(value) {
      api = value;
    }
  }
}));

Inside the HTML / Web card JavaScript runtime, the API is also available as:

ddc
helpers.ddc
helpers.dashboard

API Object

The API object exposes:

api.version
api.card
api.settings

api.getSetting(key)
api.setSetting(key, value, options)
api.setSettings(patch, options)
api.toggleSetting(key, options)
api.enableSetting(key, options)
api.disableSetting(key, options)
api.listSettings()
api.saveSettings(options)
api.openSettings()
api.saveLayout(silent)
api.setEditMode(enabled)

Reading Settings

Read one setting:

api.getSetting('auto_save');
api.getSetting('background_mode');
api.getSetting('screen_saver_enabled');

Read all exportable options:

api.settings.all();
api.settings.options();

List all known settings with type and current value:

api.listSettings();

Each item returned by listSettings() looks like:

{
 key: 'auto_save',
 type: 'boolean',
 value: true,
 boolean: true
}

Updating Settings

Update one setting:

await api.setSetting('animate_cards', true);

Update multiple settings:

await api.setSettings({
 animate_cards: true,
 background_mode: 'particles',
 screen_saver_enabled: true
});

Persist immediately:

await api.setSetting('auto_save', false, { persist: true });

Skip layout recalculation when changing a setting that does not need it:

await api.setSettings({
 debug: true
}, { recalc: false });

Boolean Helpers

Toggle a boolean setting:

const enabled = await api.toggleSetting('screen_saver_enabled');

Force a setting on:

await api.enableSetting('animate_cards');

Force a setting off:

await api.disableSetting('debug');

Saving

Save settings:

await api.saveSettings();

Save settings without trying to update YAML/storage config:

await api.saveSettings({ yaml: false });

Save the full layout:

await api.saveLayout();

saveSettings() returns a result like:

{
 backend: true,
 yaml: true,
 local: false
}

Opening Settings

Open the Drag & Drop Card dashboard settings dialog:

api.openSettings();

Edit Mode

Enable or disable Drag & Drop Card Edit Mode:

api.setEditMode(true);
api.setEditMode(false);

This controls Drag & Drop Card Edit Mode, not Home Assistant’s native dashboard edit mode.

Change Events

Subscribe to API-driven setting changes:

const unsubscribe = api.settings.subscribe((detail) => {
 console.log(detail.keys);
 console.log(detail.patch);
 console.log(detail.before);
 console.log(detail.after);
});

Stop listening:

unsubscribe();

The event detail contains:

{
 source: 'api',
 keys: ['animate_cards'],
 patch: { animate_cards: true },
 before: {},
 after: {}
}

If the change was persisted with { persist: true }, the detail can also include:

persist: {
 backend: true,
 yaml: true,
 local: false
}

The underlying event name is:

ddc:settings-changed

Options

Most write methods accept an optional options object:

{
 persist: true,
 recalc: true,
 backend: true,
 yaml: true
}

persist: true saves after applying the change.

recalc: false skips layout recalculation.

backend: false skips backend persistence when saving.

yaml: false skips YAML/storage persistence when saving.

Setting Key Format

Canonical keys use snake_case:

auto_save
screen_saver_enabled
background_mode

Many camelCase aliases are also supported:

autoSave
screenSaverEnabled
backgroundMode

Unknown keys are ignored and logged to the browser console.

Boolean values are coerced. These work as false:

false
"false"
"0"
"off"
"no"
"disabled"
"disable"

These work as true:

true
"true"
"1"
"on"
"yes"
"enabled"
"enable"

Object and array settings can be passed as JavaScript values. JSON strings are parsed when possible.

Supported Settings

Core and behaviour:

storage_key: string
grid: number
drag_live_snap: boolean
auto_save: boolean
auto_save_debounce: number
debug: boolean
disable_overlap: boolean
edit_mode_pin: string
animate_cards: boolean

Layout and responsive settings:

auto_resize_cards: boolean
optimize_for_mobile: boolean
mobile_dynamic_behavior: string
do_not_resize_text: boolean
outer_grid_buffer: boolean
outer_grid_buffer_cells: number
responsive_viewports: object
container_size_mode: string
container_fixed_width: number
container_fixed_height: number
container_preset: string
container_preset_orientation: string

Appearance:

container_background: string
apply_background_to_page: boolean
card_background: string
card_shadow: boolean
card_shadow_intensity: number
dashboard_theme: string
dashboard_theme_override_all_design: boolean

Home Assistant Sidebar & Header:

hide_HA_Header: boolean
hide_HA_Sidebar: boolean

Tabs:

tabs: array
tabs_position: string
default_tab: string
hide_tabs_when_single: boolean

Layers:

layers_enabled: boolean
layers: array

Background:

background_mode: string
background_image: object
background_particles: object
background_youtube: object

Screen saver:

screen_saver_enabled: boolean
screen_saver_delay: number
screen_saver_style: string
screen_saver_entities: array

Connectors:

connectors: array
responsive_connectors: object

Important Notes

The current API is focused on dashboard settings, layout saving, settings persistence, and edit mode control.

It does not currently expose a full card CRUD API for adding, deleting, moving, or resizing individual cards directly.

Packages are saved as part of the layout/backend payload, but they are not currently exposed as a dedicated API namespace.

For advanced integrations, prefer setSettings() over many separate setSetting() calls. It is cleaner and avoids unnecessary repeated recalculation.

For changes that should survive reloads, always use { persist: true } or call saveSettings() after applying changes.