# Main Options

| Name | JS | Type | Default | Supported options | Description |
| --- | :-: | --- | --- | --- | --- |
| `type` | :no_entry_sign: | string | **Required** | `custom:button-card` | Type of the card |
| `template` | :no_entry_sign: | string | optional | any valid template from `button_card_templates` | See [configuration template](../advanced/config-templates.md) |
| `entity` | [:white_check_mark:](../advanced/js-templates.md) <br/>(init only) | string | optional | `switch.ac` | entity_id |
| `section_mode` | :no_entry_sign: | boolean | optional | `true` \| `false` | Set it to `true` when the card is used in a sections view. See [Sections views](../advanced/section-views.md) |
| `group_expand` | :no_entry_sign: | boolean | false | `true` \| `false` | When `true`, if any of the entities triggering a card update is a group, it will auto-expand the group and the card will update on any child entity state change. This works with nested groups too. |
| `update_timer` | [:white_check_mark:](../advanced/js-templates.md) | number or string | optional | number >= 100 (ms), string duration in english supported by `helpers.parseDuration` >= 100 (ms) | Set to a duration greater than or equal to 100ms to **only** update the card at this refresh rate. This should only be used when the card has no entity. If this field is a [JS template](../advanced/js-templates.md), it will be evaluated on each refresh of the card. |
| `icon` | [:white_check_mark:](../advanced/js-templates.md) | string | optional | `mdi:air-conditioner` | Icon to display. Will be overridden by the icon defined in a state (if present). Defaults to the entity icon. Hide with `show_icon: false`. |
| `name` | [:white_check_mark:](../advanced/js-templates.md) | string | optional | `Air conditioner` | Define an optional text to show below the icon. |
| `state_display` | [:white_check_mark:](../advanced/js-templates.md) | string | optional | `On` | Override the way the state is displayed. |
| `label` | [:white_check_mark:](../advanced/js-templates.md) | string | optional | Any string that you want | Display a label below the card. See [Layouts](../advanced/layout.md) for more information. |
| `show_name` | :no_entry_sign: | boolean | `true` | `true` \| `false` | Wether to show the name or not. Will pick entity_id's name by default, unless redefined in the `name` property or in any state `name` property |
| `show_state` | :no_entry_sign: | boolean | `false` | `true` \| `false` | Show the state on the card. defaults to false if not set |
| `numeric_precision` | :no_entry_sign: | number | none | any number | Force the display precision of the state to be with `numeric_precision` decimals |
| `show_icon` | :no_entry_sign: | boolean | `true` | `true` \| `false` | Wether to show the icon or not. Unless redefined in `icon`, uses the default entity icon from hass |
| `show_units` | :no_entry_sign: | boolean | `true` | `true` \| `false` | Display or hide the units of a sensor, if any. |
| `show_label` | :no_entry_sign: | boolean | `false` | `true` \| `false` | Display or hide the `label` |
| `show_last_changed` | :no_entry_sign: | boolean | `false` | `true` \| `false` | Replace the label altogether and display the the `last_changed` attribute in a nice way (eg: `12 minutes ago`) |
| `show_ripple` | [:white_check_mark:](../advanced/js-templates.md) | boolean | optional | `true` or `false` | If defined, this will enable or disable the ripple/hover effect on the card. If undefined, the ripple/hover effect is automatically enabled if the card has at least an action defined (including the default one based on the entity). |
| `show_entity_picture` | :no_entry_sign: | boolean | `false` | `true` \| `false` | Replace the icon by the entity picture (if any) or the custom picture (if any). Falls back to using the icon if both are undefined |
| `show_live_stream` | :no_entry_sign: | boolean | `false` | `true` \| `false` | Display the camera stream (if the entity is a camera). Requires the `stream:` component to be enabled in home-assistant's config |
| `live_stream_aspect_ratio` | :no_entry_sign: | string | optional | `16x9`, `50%`, `1.78` ... | See home-assistant Picture Entity card [aspect_ratio](https://www.home-assistant.io/dashboards/picture-entity/#aspect_ratio) for valid options |
| `live_stream_fit_mode` | :no_entry_sign: | string | optional | `cover`, `contain`, `fill` | See home-assistant Picture Entity card [fit_mod](https://www.home-assistant.io/dashboards/picture-entity/#fit_mode) for information on how each option works |
| `entity_picture` | [:white_check_mark:](../advanced/js-templates.md) | string | optional | Can be any of `/local/*` file or a URL | Will override the icon/the default entity_picture with your own image. Best is to use a square image. You can also define one per state. |
| `units` | :no_entry_sign: | string | optional | `Kb/s`, `lux`, ... | Override or define the units to display after the state of the entity. If omitted, it's using the entity's units |
| `color_type` | :no_entry_sign: | string | `icon` | `icon` \| `card` \| `blank-card` \| `label-card` | Color either the background of the card or the icon inside the card. Setting this to `card` enable automatic `font` and `icon` color. This allows the text/icon to be readable even if the background color is bright/dark. Additional color-type options `blank-card` and `label-card` can be used for organisation (see examples). |
| `color` | :no_entry_sign: | string | optional | `auto` \| `auto-no-temperature` \| `rgb(28, 128, 199)` | Color of the icon/card. `auto` sets the color based on the color of a light including the temperature of the light. Setting this to `auto-no-temperature` will behave like home-assistant's default, ignoring the temperature of the light. By default, if the entity state is `off`, the color will be `var(--state-inactive-color)` for icon and `var (--card-background-color)` for card, for `on` it will be `var(--state-active-color)` and for any other state it will be `var(--primary-text-color)`. You can redefine each colors using `state` |
| `size` | :no_entry_sign: | string | `40%` | `20px` | Size of the icon. Can be percentage or pixel |
| `aspect_ratio` | :no_entry_sign: | string | optional | `1/1`, `2/1`, `1/1.5`, ... | See [Aspect Ratio](../advanced/aspect-ratio.md) for an example. Aspect ratio of the card. `1/1` being a square. This will auto adapt to your screen size |
| `rotate` | [:white_check_mark:](../advanced/js-templates.md) | boolean | `false` | `true` \| `false` | If `true`, the entity_picture or icon will rotate |
| `tap_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action on click, if undefined, toggle will be used for domains that support toggle, or button press for input_button. |
| `hold_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action on hold, if undefined, nothing happens. |
| `double_tap_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action on double click, if undefined, nothing happens. |
| `press_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action to execute immediately on button press. If defined, the only other card action allowed is `release_action` |
| `release_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action to execute on button release. If defined, the only other card action allowed is `press_action` |
| `icon_tap_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action on icon click, if undefined, nothing happens. When configured, the icon becomes clickable separately from the card. See note in [icon\_\*\_action](./actions.md#icon__action) |
| `icon_hold_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action on icon hold, if undefined, nothing happens. When configured, the icon becomes holdable separately from the card. See note in [icon\_\*\_action](./actions.md#icon__action) |
| `icon_double_tap_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action on icon double click, if undefined, nothing happens. When configured, the icon becomes double-clickable separately from the card. See note in [icon\_\*\_action](./actions.md#icon__action) |
| `icon_press_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action to execute immediately on icon press. If defined, the only other icon action allowed is `icon_release_action`. See note in [icon\_\*\_action](./actions.md#icon__action) |
| `icon_release_action` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [Action](./actions.md) | Define the type of action to execute on icon release. If defined, the only other icon action allowed is `icon_press_action`. See note in [icon\_\*\_action](./actions.md#icon__action) |
| `styles` | :no_entry_sign: | object list | optional |  | See [styles](../advanced/styling.md) |
| `extra_styles` | [:white_check_mark:](../advanced/js-templates.md) | string | optional |  | See [styles](../advanced/styling.md#injecting-css-with-extra_styles) |
| `state` | :no_entry_sign: | object list | optional | See [State](./state.md) | State to use for the color, icon and style of the button. Multiple states can be defined |
| `confirmation` | [:white_check_mark:](../advanced/js-templates.md) | object | optional | See [confirmation](./actions.md#confirmation) | Display a confirmation popup |
| `lock` | :no_entry_sign: | object | optional | See [Lock Object](./lock.md) | Displays a lock on the button |
| `layout` | :no_entry_sign: | string | optional | See [Layout](../advanced/layout.md) | The layout of the button can be modified using this option |
| `custom_fields` | :no_entry_sign: | object | optional | See [Custom Fields](../advanced/custom-fields.md) |
| `variables` | :no_entry_sign: | object | optional | See [Variables](../advanced/js-templates.md#variables) |
| `card_size` | :no_entry_sign: | number | 3 | Any number | Configure the card size seen by the auto layout feature of lovelace (lovelace will multiply the value by about 50px) |
| `tooltip` | [:white_check_mark:](../advanced/js-templates.md) | string or object | optional | See [Tooltips](./tooltip.md) | Display a tooltip. (Not supported on touchscreens). |
| `hidden` | [:white_check_mark:](../advanced/js-templates.md) | boolean | optional | `false` | Shows or hides the card. Supports templates. |
| `disable_kbd` | :no_entry_sign: | boolean | `false` | `true` or `false` | Disable keyboard `enter` and `space` capture on the button itself. Usefull when you have input fields inside the button. |
| `spinner` | [:white_check_mark:](../advanced/js-templates.md) | boolean | `false` | `true` or `false` | See [spinner](../advanced/spinner.md). If `true`, it will lock the card and display a spinner. You'll need to use a template or `state` to make this variable. |
| `protect` | [:white_check_mark:](../advanced/js-templates.md) | object | none | See [protect](./actions.md#protect) | Display a password or PIN confirmation popup. |
