The User SVG tool¶

1.0.0 · Output ·

The User SVG tool makes it possible to add (external) SVGs, JPGs and PNGs ( 1.0.0-rc.3) to your card.

1.0.0-rc.3 It has also support for clipping and masking, so your external SVG/JPG/PNG will fit the area (from rectangle/square to round) it is displayed within.

Weather	Weather	AirVisual	AirVisual

An example using clipping and masking: A square image of a washing machine is now fit to the round circle. Furthermore, all images and svgs have an opacity mask.

Swiss Army Knife Clip Mask example

Inline SVG support is foreseen in the future

Basic usage¶

Static fileConnected

From: view-sake6
- type: 'usersvg'           # tooltype is 'usersvg'
  position:                 # Position on (100x100) canvas
    cx: 50                  # cx=50 is center position
    cy: 50                  # cy=50 is center position
    height: 100             # Image covers full heigth and...
    width: 100              # ...width of card.
  style: 'images'
  images:                   # A static image uses 'default':
    - default: /local/images/backgrounds/balls-background-1.svg

This one is taken from example 1, the display of the 'face' used for AirVisual.

From: view-sake1
- type: 'usersvg'           # tooltype is 'usersvg'
  position:                 # Position on (100x100) canvas
    cx: 50                  # cx=50 is center position
    cy: 50                  # cy=50 is center position
  entity_index: 0           # connect to state of entity 0
  style: 'images'
  images:
    - face1: /local/images/ic-face-1.svg
    - face2: /local/images/ic-face-2.svg
    - face3: /local/images/ic-face-3.svg
    - face4: /local/images/ic-face-4.svg
    - face5: /local/images/ic-face-5.svg
    - face6: /local/images/ic-face-6.svg
  animations:               # Use animation to switch faces
    - state: '50'
      operator: <=
      image: face1
    - state: '100'
      operator: <=
      image: face2
    - state: '150'
      operator: <=
      image: face3
    - state: '200'
      operator: <=
      image: face4
    - state: '300'
      operator: <=
      image: face5
    - state: '9999'
      operator: <=
      image: face6

Advanced usage¶

This example shows how to clip/mask an image or svg.

Connected

From: view-sake1
- type: 'usersvg'
  entity_index: 3
  position:
    cx: 50
    cy: 50
    height: 95
    width: 95
  clip_path:
    position:
      cx: 50
      cy: 50
      height: 90      # clip height and width to a bit
      width: 90       # smaller than image size (95/95)
      radius:         # Irrelevant, since mask will make
        all: 45       # a circle out of this image!
  style: 'images'
  images:
    - face1: /local/images/clip-test.jpg
    - face2: /local/images/airvisual/ic-face-2.svg
    - face3: /local/images/airvisual/ic-face-3.svg
    - face4: /local/images/airvisual/ic-face-4.svg
    - face5: /local/images/airvisual/ic-face-5.svg
    - face6: /local/images/airvisual/ic-face-6.svg
  animations:
    - state: '50'
      operator: <=
      image: face1
    - state: '100'
      operator: <=
      image: face2
    - state: '150'
      operator: <=
      image: face3
    - state: '200'
      operator: <=
      image: face4
    - state: '300'
      operator: <=
      image: face5
    - state: '9999'
      operator: <=
      image: face6
  styles:
    usersvg:
      stroke-width: 5em
    mask:
      fill: url(#sak-mask-radial-gradient)    

Styling¶

As of 2.4.2, styling of external SVG is possible (again)

The User SVG tool has support for the following forms of styling:

Method	Support	Description
`classes`		Using SAK or User defined class definitions
`styles`		Using inline SVG and CSS styles

For styling to work, the external SVG must be suitable to get styled

See: Make pollen SVGs stylable

Things that must be removed in the SVG to allow for external styling are:

Inline style definitions
Inline class definitions in the section of the SVG

Things that do work are:

Usage of class definitions wich can be overridden externally
Usage of CSS variables which can be set externally

Safari has problems with certain styling

CSS Filters don't work. Use SVG filters instead!
Also, chaining filters in Safari does NOT work. Use combined SVG filters instead.
For any other Safari problem where things work in Chrome: wait for the new SVG engine

The User SVG tool is composed of a single object: "usersvg" and this is the selector for styling:

- type: 'usersvg'
  position:
    cx: 50
    cy: 50
  classes:
    usersvg:                # Usersvg selector
      <...>
  styles:
    usersvg:                # Usersvg selector
      <...>

Populair properties:

Property	Does what?	Example
opacity	Makes image transparent	opacity: 0.5 (for 50% opacity)

Styling: Injected vs external SVGs¶

External SVGs can't be styled, so-called 'injected' SVGs can be styled.

The default behaviour of the User SVG tool is to 'inject' the external SVGs into the tool.

However, if the SVG contains local styling and class definitions, and the same SVG is used more than once in a card, you can run into styling problems (internal classes overwrite each other), and you have to force the SVGs to remain external images.

This can be done as follows:

  options:
    svginjection: false     # true (default) for injection,
                            # false for keeping the external file

Haptics¶

See: https://companion.home-assistant.io/docs/integrations/haptics/ for devices that support haptics

The tool supports haptic feedback through user_actions/ tap_action definition

Action	Haptic	Description
Click	`haptic`	Uses the haptic property defined in the `user_actions` definition of the tool. If not specified, a default of `medium` is used

  tools:
    - type: icon
      position:
        cx: 10
        cy: 10
        align: center
        icon_size: 15
      entity_index: 0
      user_actions:
        tap_action:
          haptic: success
          actions:
            - action: more-info

Possible values for haptic feedback:

Haptic	Description
success	Indicates that a task or action has completed.
warning	Indicates that a task or action has produced a warning of some kind.
failure	Indicates that a task or action has failed.
light	Provides a physical metaphor that complements the visual experience.
medium	Provides a physical metaphor that complements the visual experience.
heavy	Provides a physical metaphor that complements the visual experience.
selection	Indicates that the selection is actively changing.

Animations¶

The User SVG tool has support for the following forms of animations:

Method	Support	Description
`colorstops`		List of state values to set the color
`colorlists`		Using a colorlist definition
`animations`		Operator state based animations with class/style styling

The use of animations require the tool to be connected to an entity

Detailed specification¶

The basic and advanced usage shows all the functionalities of the User SVG tool.