DOCSEARCHbyAlgolia
Submit Docs

Universal Remote Card

repository·main·Indexed 20 days ago

https://github.com/nerwyn/universal-remote-card

A highly customizable Home Assistant dashboard card providing a unified remote control interface for media platforms including Android TV, Apple TV, Roku, LG webOS, Samsung TV, Fire TV, Kodi, and others. It features a built-in configuration UI, support for custom CSS styling, and specialized layout elements like circlepads, touchpads, and sliders. The card supports various integrations such as ADB for Sony BRAVIA and Fire TV, and custom integrations for Unified Remote, Yamaha YNCA, and Unfolded Circle.

Tokens
23.7K
Snippets
37
Records
68
Agent score
69%

What's inside universal-remote-card

  1. Configure remote layout using rows and columns

    main

    The layout of the remote is defined by the rows configuration key. Each row is an array of elements.

    Layout Patterns:

    • Simple Row: A list of button names (e.g., - [power, back, home]).
    • Empty Spaces: Adding null to a row creates an empty button-sized space, useful for alignment.
    • Nested Layouts: You can nest arrays within rows to create columns. A row containing arrays (e.g., - [ [button1, button2], [button3] ]) creates a grid-like structure of columns within that row.
    • Special Elements: Elements like touchpad, slider, dpad, or volume_buttons can be mixed with standard buttons.
    # Example of nested columns and empty spaces
rows:
  - - back
    - home
    - tv
  - - rewind
    - null
    - null
    - fast_forward

# Example of a tablet layout with nested rows and columns
rows:
  - - - - back
        - null
        - home
        - null
        - menu
      - - volume_down
        - null
        - volume_mute
        - null
        - volume_up
    - - - keyboard
        - search
      - - touchpad

  2. Use Nunjucks templating in remote elements

    main

    Most fields support Nunjucks templating (a JavaScript engine similar to Jinja2).

    Available Variables

    • value: The current value of the remote element.
    • unit: The units of the remote element.
    • hold_secs: Useful when performing momentary repeat or end actions.
    • initialX, initialY, currentX, currentY, deltaX, deltaY: Touch location information (useful for drag interactions on touchpads).

    Accessing Configuration

    • config.entity: Returns the element's entity ID (with templates rendered).
    • config.attribute: Returns the element's attribute (with templates rendered).
    • config.card: Accesses the entire card configuration.
    • config.card.remote_id: Accesses the global remote ID.
    • render(field): Use this function to render other templated configuration fields within a template.

    Note: If a field has a default value that is not explicitly in the config, you must handle it in your template using the or operator, e.g., config.card.platform or 'Android TV'.

  3. Understand button and touchpad interaction types

    main

    The card supports three primary interaction modes for buttons and the touchpad center: tap, double tap, and hold.

    • Buttons & Touchpad Center: Support tap, double tap, and hold.
    • Touchpad Swipes: Support only tap and hold.
    • Sliders: Support only tap actions.

    Note: Defining a double tap action (that is not none) introduces a 200ms delay to all single tap actions to allow for the double-tap detection window.

  4. Create Custom Remote Elements

    main

    You can create custom buttons, sliders, or touchpads to extend the remote's functionality.

    • Overwriting Defaults: To overwrite a default key or source (like the default touchpad), create a custom element with the exact same name as the default one.
    • Autofill: If Autofill is enabled (globally or per element), the editor will automatically populate action targets based on the general tab settings or the element's entity/global IDs.
    • External Configuration: To avoid duplicating custom elements across multiple cards, you can store them in a JSON or YAML file in your Home Assistant config/www folder and fetch them by filename (e.g., local/remote_card_custom_elements.yaml).

  5. Configure momentary mode for buttons

    main

    Momentary mode allows a button to trigger different actions based on the press/release lifecycle, bypassing standard tap/hold/double-tap logic.

    • Momentary Start: Fired when the button is first pressed down.
    • Momentary End: Fired when the button is released.
    • Momentary Repeat: Fired when the button is held for a set number of milliseconds.

    To use this, configure the momentary options in the UI. For the momentary end action, you can include the duration the button was held using the hold_secs variable in a template.

  6. Configure Circlepad and Touchpad Remote Elements

    main

    Circlepads and touchpads are organized into five tabs representing the directions (Up, Down, Left, Right) and the Center.

    • Center Tab: Contains the General Options that apply to the entire touchpad/circlepad element.
    • Directional Tabs: Each direction and the center have their own specific settings for appearance and interaction logic.

  7. Configure touchpad and circlepad interactions

    main

    Touchpad

    • Direction Swipes: Activated by swiping. Hold actions on directions repeat by default.
    • Multi-touch Mode: Enabled by setting multi-touch actions to something other than Nothing. Supports center tap, double tap, hold, and direction swipes.
    • Drag Mode: Triggered by movement. Provides deltaX and deltaY via templates. Use the Sampling delay configuration to control the fire rate and speed of drag movements.

    Circlepad

    • Buttons: Each of the five buttons supports standard interactions.
    • Clickwheel: Uses the outer ring. Use the clockwise template boolean to determine the direction of the drag.

  8. Customize Remote Card Styles with CSS

    main

    You can style the card and its sub-elements using standard CSS and templating. Styles must be encapsulated within a CSS selector. You can use the ::part() pseudo-element to style specific parts of an element (like an icon) without needing to create a custom element.

    Common CSS Selectors

    SelectorTarget
    :hostThe card or sub-element host
    .rowAll rows
    .columnAll columns
    .button-padAll default button pads
    .empty-buttonAll empty/null button spaces
    remote-buttonAll buttons
    #row-1The first row
    #column-1The first column
    #pad-1The first button default pad
    #powerA specific element by name
    #power::part(icon)The icon of a specific element

    Tip: Hovering over the card preview in the editor shows a red dashed outline and a tooltip indicating the correct selector (element name, row, column, or pad ID).

    /* All rows */
.row {
  justify-content: center;
}

/* All buttons */
remote-button {
  background: rgb(27, 27, 27);
  padding: 8px;
  margin: 4px;
  border-radius: 24px;
  --icon-size: 24px;
}

/* The icon of the power button */
#power::part(icon) {
  color: red;
}

  9. Configure Sony BRAVIA with Keyboard and Search

    main

    Some Sony BRAVIA models use a proprietary API instead of the Android TV Remote API. To enable keyboard and search functionality on these models, you must:

    1. Use the Sony BRAVIA platform.
    2. Set up the Android Debug Bridge (ADB) integration.
    3. Provide the ADB remote or media player entity ID in the Keyboard ID field of the card configuration.

  10. Configure Fire TV via Android Debug Bridge

    main
    Fire TV is a modified version of Android TV. If your device does not support the standard Android TV Remote API, use the Fire TV platform in the card, which relies on the Android Debug Bridge (ADB) integration for all interactions (keys, keyboard, search, etc.).

  12. Configure Keyboard accessibility and shortcuts

    main

    You can control the remote card using your physical keyboard:

    • Navigation: Use Tab to focus elements, and Arrow keys or Space/Enter to actuate them.
    • Custom Keys: Assign any physical key to a specific button using the Keyboard Key field in the interaction pane.
    • Directional Input: If no button is assigned, typing arrow keys or space/enter while focused on the card will send input to the first circlepad or touchpad.
    • Multi-touch/Clickwheel: Hold the Shift key to forward multi-touch or clickwheel actions to touchpads and circlepads.