Arguments
Flow arguments allow Flow cards to ask for user input.
Flow card arguments are passed as an input to your Flow card, users can pick the argument values when creating or editing a Flow.
Arguments must have a type
that determines how they are shown. For example, a dropdown
argument allows a user to pick one value from a predefined set of options, whereas a text
argument shows an input field.
Don't overuse arguments! In our experience, Flow cards with just one or two arguments are the most popular.
Argument Types
The following are all available argument types that you can use in your Flow cards and the options that you can use with those types.
Text
"type": "text"
Regular text input. Text, Number and Boolean tokens can be dropped in this field as well.
Attributes
Name | Type | Description | Example |
placeholder | Text to show without input |
| |
title | Text shown above argument |
|
Example
Autocomplete
"type": "autocomplete"
This is the same as a text input, but with an additional autocomplete popup. The returned value when the card is run, is one of the objects provided in the autocomplete array. In order to provide autocomplete results you need to register an autocomplete listener for the Flow card with FlowCard#registerArgumentAutocompleteListener()
Attributes
Name | Type | Description | Example |
placeholder | Text to show without input |
| |
title | Text shown above argument |
|
Example
If you don't filter based on the query, it will cause the autocomplete results to appear unresponsive. The easiest way to filter the results is to compare name
and query
in lowercase as shown above.
Number
"type": "number"
Regular text input. Tokens can be dropped in this field as well.
Attributes
Name | Type | Description | Example |
min |
| Minimum input value | 40 |
max |
| Maximum input value | 90 |
step |
| Step size | 10 |
placeholder | Text to show without input |
| |
title | Text shown above argument |
|
Example
Range
"type": "range"
A slider with a minimum and maximum value.
Attributes
Name | Type | Description | Example |
min |
| Minimum input value | 0 |
max |
| Maximum input value | 1 |
step |
| Step size | 0.01 |
label |
| The units after the number | % |
labelMultiplier |
| Number is shown after multiplying by this factor | 100 |
labelDecimals |
| Number of decimals to round to | 2 |
title | Text shown above argument |
|
Example
Date
"type": "date"
Date input (presented in dd-mm-yyyy
)
Attributes
Name | Type | Description | Example |
placeholder | Text to show without input |
| |
title | Text shown above argument |
|
Example
Time
"type": "time"
Time input (presented in HH:mm
)
Attributes
Name | Type | Description | Example |
placeholder | Text to show without input |
| |
title | Text shown above argument |
|
Example
Dropdown
"type": "dropdown"
A dropdown list with pre-defined values
Attributes
Name | Type | Description | Example |
values |
| An array of possible values |
|
title | Text shown above argument |
|
Example
Checkbox
"type": "checkbox"
A dropdown list with a true and false option that supports boolean tokens.
Attributes
Name | Type | Description | Example |
title | Text shown above argument |
|
Example
Color
"type": "color"
A color picker that returns a HEX color, e.g. #FF0000
.
Example
Droptoken
A droptoken is a special Flow card Argument that only allows the user to enter a Flow Token or Homey Logic variable. You can add a droptoken to your Flow card by specifying, for example, "droptoken": ["number"]
. You can use the any of the following types: string
, number
, boolean
or image
. A Flow card can only have a single droptoken but you can specify multiple allowed types.
Droptokens are possibly null. Make sure to verify the droptoken exists before using it.
Example
Device
"type": "device"
When you add a device argument to your flow card, and provide a driver_id
filter, e.g. "filter": "driver_id=yourdriverid"
, the Flow card will only be displayed for devices that belong to that specific driver.
If the device was already there because the device's class is a supported device class (e.g. light
), your cards will be appended to the existing stack of cards. An example would be a Light driver that has a 'disco' mode, next to on/off, dim and color.
If the card has more than one device fields, the other fields will behave like an autocomplete-like argument, which show devices paired in your app.
See the Flow guide Device cards section for more information about device arguments and filters.
Optional arguments
By default all Flow card arguments are required however if you want to allow an argument to be optional you can set the required
property to false
.
If an argument is not required and is not provided by the user it may be undefined
in your Flow card run handler.
Example
Action Card duration
If you are creating an Action Flow card, a card for the ...then column, you can set the duration
property. This property allows users to choose a duration for the action. If a user provides this argument to the Flow card, it will be passed to the card handler as an argument named duration
in milliseconds.
"duration": true
has precedence over an argument with "name": "duration"
as they are both provided as arguments to the same handler. You should not create a Flow card with the duration
property and an argument named "duration".
Example
Subscribing to argument changes
It might be useful to know when a trigger has changed. For example a Twitter app may have a Flow card that triggers a Flow when a specific hashtag is tweeted. In order to implement this behaviour the app needs to know what hashtags to search for. By subscribing to argument changes the app knows when the argument values have changed and update the list of hashtags it is looking for.
Flow State
When a Flow is triggered and the Flow Trigger card has arguments, your app needs to validate that the current state matches with the arguments the user chose for the Flow. This listener is executed for each Flow that uses this Flow Trigger card.
For example, a rain_start
Flow Trigger card can have a location
argument so that the Flow is only triggered when it is raining in the place the user has selected.
Last updated