# Patterns
Patterns define the interactions and data that are exposed and collected by an app. A pattern definition is a YAML document that defines the UI elements of an app. Every UI element is an object with a set of properties that define its looks and behavior. Routegy supports numerous built-in element types that range from simple text inputs (type: text
) to more advanced and specialized components like Net Promoter Score element (type: nps
).
# Example
The following is an example YAML pattern for an app that collects information about a problem with an office printer. This UI pattern includes a list of checkboxes that map to a list of predefined problem categories, and an additional_problem_info
textarea field for additional details or miscellaneous problems not included in the list.
problem:
type: checkboxes
items:
- Doesn't turn on
- Paper jam
- No paper
- No toner
- Connectivity issue
- Something else
title: What's going on?
additional_problem_info:
type: textarea
title: Something else or more details?
placeholder: E.g. Printer screen shows E104 error, cannot be reset and doesn't print
The following is the same pattern rendered by Routegy.

Once submitted, data collected by this app will be a JSON object with two properties: problem
array property and additional_problem_info
string property. Example:
{
"problem": [
"No paper",
"No toner"
],
"additional_problem_info": "No supplies can be found anywhere in the print room."
}
# Element properties
Every element is defined as a YAML object with a set of properties that determine the type, appearance, and behavior of a UI component to be rendered in the app. Below is a list of properties that are support in most of the built-in components.
Property | Description |
---|---|
type | Determines the type of the UI element. If type property is not defined, the object is treated as a fieldset. If type is defined, it must be one of the supported element types. |
label (also caption and title ) | Defines a label for the UI element (optional). |
visible | Conditional visibility expression (optional). |
default | The default value for the element (optional). Supported by all built-in elements except for markdown . |
required | Set to true to make entering a valid value into this element mandatory. |
placeholder | Placeholder string (optional). Supported by elements based on the text input including text , textarea , email , phone , etc. |
items | List of items for multiple or single choice elements like radio buttons and checkboxes. |
tooltip | Adds a tooltip to a label that appears on hover or touch. You can also specify tooltipSize as small , medium (default), or large , as well as tooltipPosition as top , right (default), bottom , or left . |
# Supported element types
Type | Description |
---|---|
string, text | Basic text input |
textarea | Multiline textarea input |
date | Date input based on HTML date input type |
datetime | Datetime input based on HTML datetime-local input time |
Email input based on HTML email input type | |
time | Time input based on HTML time input type |
uri, url | Url input based on HTML url input type |
phone | Text input with a RegEx pattern matching US phone numbers] |
password | Masked text input for senstive information |
number, integer | Integer input with up-and-down controls |
radio, radios, radiobuttons | Multiple radio buttons |
dropdown | Dropdown select input |
checkboxes | Multiple checkboxes |
checkbox, boolean | Single checkbox |
tags | Tag input |
markdown | Markdown element to display static information |
# Text inputs
To render a text input, use a text
or string
type and customize its appearance with title
and placeholder
properties.
text_input:
type: text
label: Text input
placeholder: Input some text here

# Regular expressions
To render a text input with automatic validation against a regular expression pattern, set the pattern
property inside the element of a text
or string
type
to a desired RegEx pattern.
api_key:
type: string
pattern: '^[0-9a-zA-Z]{32}$'
label: API key

# HTML input types
Routegy offers built-in support for various HTML input types. Here is a list element types mapped to supported HTML input types.
Routegy element type | HTML input type |
---|---|
date | date |
datetime | datetime-local |
time | time |
uri | url |
Below is an example of a pattern that contains inputs of email
and date
types.
email:
type: email
label: Email address
placeholder: E.g. john.doe@email.org
dob:
type: date
label: Date of birth

# Passwords and other masked inputs
WARNING
Be extremely careful when requesting sensitive data in your apps. If you're unsure about how best to process sensitive data, please contact us at support@routegy.com.
Masked text inputs can be helpful when collecting sensitive information like passwords. To render one, set the element's type to password
.
password:
type: password
label: Password
placeholder: Enter your password here

# Text area
To render a textarea, set the element's type to textarea
.
comments:
type: textarea
label: Any comments?

# Number input
To render a number input with up and down buttons, set element's type to integer
or number
. Optionally, set minimum
and maximum
properties attributes to define the allowed range, and set a default value using the default
property.
count:
type: integer
label: Count
default: 5
maximum: 10
minimum: 1

# Radio buttons
To render a group of radio buttons, set the element's type to radio
, radios
or radiobuttons
and define a list of their values/labels using the items
array property.
options:
type: radios
label: Choose one of the following
items:
- Option 1
- Option 2
- Option 3

# Item data types
By default, values listed under items
property have to be defined as strings. This can be overridden by using dataType
property that can be set to one of the following primitive types: string
, integer
, boolean
.
Below is an example pattern with radio buttons mapped to some integer values.
options:
type: radios
dataType: integer
label: Select a number
items:
- 1
- 2
- 3
# Custom labels
Labels for individual radio buttons can be customized by turning items of the items
property into objects with value
and label
properties. This can be combined with a custom dataType
to map non-string values to text labels. Below is an example of a pattern with two radio boxes mapped to true
and false
boolean values that are labeled as Yes and No respectively.
options:
type: radios
label: What is your answer?
dataType: boolean
items:
- value: true
label: Yes
- value: false
label: No

# Select input
To render a dropdown select input, set the element's type to dropdown
and define a list of dropdown items items using the items
property.
options:
type: dropdown
label: Choose one of the following
items:
- Option 1
- Option 2
- Option 3

# Item data types
By default, values listed under items
property have to be defined as strings. This can be overridden by using dataType
property that can be set to one of the following primitive types: string
, integer
, boolean
.
Below is an example pattern with a dropdown list of integer values.
options:
type: dropdown
dataType: integer
label: Choose one of the following
items:
- 1
- 2
- 3
# Single checkbox
To render a single checkbox, define an element of type checkbox
or boolean
.
checkbox:
type: checkbox
label: Checkbox example

# Multiple checkboxes
To render a group of checkboxes, set the type to checkboxes
and define a list of checbox values and labels using the items
property.
checkboxes:
type: checkboxes
label: Select all that apply
items:
- Option one
- Another option
- One more option
- Last option

# Item data types
By default, values listed under items
property have to be defined as strings. This can be overridden by using dataType
property that can be set to one of the following primitive types: string
, integer
, boolean
.
# Custom labels
Labels for individual checkboxes can be customized by turning items of the items
property into objects with value
and label
properties. This can be combined with a custom dataType
to map non-string values to text labels.
Below is an example pattern with checkboxes that represent integer values labeled with number names. The resulting pattern data will be an array of integers, E.g. [10, 10000]
.
numbers:
type: checkboxes
dataType: integer
label: Choose one or more
items:
- value: 100
label: One hundred
- value: 1000
label: One thousand
- value: 10000
label: Then thousands
# Tag input
Tag input is an input element for entering a list of string tags. To render one, use the tags
element type. Optionally, the maxItems
property can be used to define a maximum number of tags allowed.
tags_example:
type: tags
maxItems: 10
label: Items to refill

# Static information
# Markdown
To render text formatted with markdown (opens new window), set the element type to markdown
and enter your markdown into the text
property.
You can dynamically display values entered from elsewhere in your pattern by referencing the value name and placing it in your markdown with the format ${your_value_name}
.
In addition to text
, you can specify the size
(small
, normal
(default), medium
, large
) and whether or not to render the markdown in a visible container with isBoxed
set to true
.
TIP
Use a pipe (|
) after the text
property keyword to allow multi-line strings in your YAML.
name:
type: string
label: Name
placeholder: Enter your name
markdownTitle:
type: markdown
size: large
text: |
# Hello ${name}!
markdown:
type: markdown
isBoxed: true
size: normal
text: |
# A first-level header
**This is bold.**
_And this is italic._
Use emoji! :) :smile: :shrug: :magic_wand:
Links are automatically parsed: URLs like www.routegy.com or email addresses like support@routegy.com
Of course [regular links](https://routegy.com) are also ok.
* a list
* is easy
* to do
::: warning
:warning: *this is a warning*
:::
::: info
:bulb: *this is informative*
:::
::: danger
:exclamation: *this is an error*
:::
::: success
:white_check_mark: *this is a success*
:::
::: primary
:point_right: *this is important*
:::
::: normal
:sleeping: *this is just boring ol' normal*
:::
# THE END

# Specialized components
# Star rating
To render a star rating widget, add an element of type rating
. Optionally, set the size
property to small
, medium
(default), or large
to customize the size of rendered stars.
experience:
type: rating
default: 4
label: How was your experience?

# Net Promotor Score
Net Promotore Score (NPS) (opens new window) can be used to quantify a customer's perception of an experience or a product by asking them how likely they are to recommend it to someone else. Routegy provides a component for collecting an NPS numerical value that can be rendered setting type to nps
.
score:
type: nps
minScoreLabel: Absolutely not!
maxScoreLabel: Yes!
label: Would you recommend this product to a friend?
Minimum and maximum score labels and score ranges are customizable using additional element properties as shown below.
Attribute name | Default value | Description |
---|---|---|
minScoreLabel | Not Very Likely | Label displayed next to the lowest score |
maxScoreLabel | Very Likely | Label displayed next to the highest score |
minScore | 0 | Lowest score on on the scale |
maxScore | 10 | Highest score on the scale |
passiveScore | 7 | Starting score for the 'passive' range (orange) |
promoterScore | 9 | Starting score for the 'promoter' range (green) |

# Conditional fields
Routegy offers support for conditionally displaying elements using simple comparison logic defined inside the visible
property of an element. This allows control of an element's visiblity based on a comparison of an elements value to another element's value or to a defined value.
For instance, the following visible
property would evaluate to true only if a value associated with the provide_more_info
element is set to true
.
visible:
provide_more_info:
equalTo: true
Since equals_to
is the default comparison operator (more on different operator below), it can be ommited and the entire expression can be reduced to:
visible:
provide_more_info: true
Below is a more complete example that demonstrates how two text inputs, defined as email
and phone
, are conditionally displayed depending on the value of the how_to_contact
radio buttons element.
how_to_contact:
type: radio
label: How would you like to be contacted?
items:
- value: by_email
label: Send me an email
- value: by_text
label: Send me a text message
email:
type: email
placeholder: E.g. you@example.com
label: Your email address
visible:
how_to_contact: by_email
phone:
placeholder: 'E.g, 555-555-5555'
label: You phone number
type: phone
visible:
how_to_contact: by_text
By default, neither email
nor phone
widgets are visible.

If how_to_contact
's value is set to by_email
(Send me an email
radio button), the email
input is made visible to collect an email address.

If how_to_contact
's value is set to by_text
(Send me a text message
radio button), the phone
input is made visible to collect a phone number.

# Comparison operators
Here is a list of comparison operators supported inside the visible
property.
Property name | Description |
---|---|
equalTo | True if the specified value is equal to the value of the specified element. |
notEqualTo | True if the specified value is not equal to the value of the specified element. |
lessThan | True if the specified value is less than the value of the specified element. Useful when working with elements that have numerical values like integer , rating or nps . |
lessThanOrEqualTo | True if the specified value is less than or equal to the value of the specified element. |
greaterThan | True if the specified value is less than the value of the specified element. Useful when working with elements that have numerical values like integer , rating or nps . |
greaterThanOrEqualTo | True if the specified value is less than or equal to the value of the specified element. |
empty | True if the specified element's value is empty or undefined. The specified value must be boolean true or false . |
notEmpty | True if the specified element's value is not empty and not undefined. The specified value must be boolean true or false . |
contains | True if the specified value is contained in the value of the specified element. Useful when working with elements associated with array values like checkboxes and tags or any text element. |
doesntContain | True if the specified value is not contained in the value of the specified element. Useful when working with elements associated with array values like checkboxes and tags or any text element. |
# Additional examples for conditional elements
Make the something_else
textarea visible only if the Something else
checkbox is checked in the problem
element. Since the value associated with the problem
element is an array of strings (values of checked checkboxes), the contains
operator is used.
problem:
type: checkboxes
title: Printer problem?
items:
- Doesn't turn on
- Paper jam
- No paper
- No toner
- Something else
something_else:
type: textarea
title: Something else or more details?
visible:
problem:
contains: Something else
Make the how_can_we_improve
textarea visible only if fewer than three stars are selected in the experience
rating element.
experience:
type: rating
size: large
label: How would you rate your experience today?
how_can_we_improve:
type: textarea
label: Please let us know how can we make the experience better
visible:
experience:
lessThan: 3
# Grouping elements into fieldsets
Combining multiple elements into a fieldset can be done by nesting them inside a parent object that doesn't have a type
property set. Fieldsets can be also nested in each other to create a multi-level hierarchy.
The sample pattern below demonstrates a simple field grouping for collecting contact information structured in the following way:
Contact info
Name
First name
Last name
Email address
To accomplish this, the following YAML definition uses three levels of nested objects. Fieldsets (Contact info
and Name
) are labeled using the label
property (optional), but they don't have a type
property like other elements.
contact_info:
label: Contact info
name:
last_name:
type: text
label: Last name
first_name:
type: text
label: First name
email:
type: email
label: Email address

# Multipage patterns
Multipage pattern can be used to organize larger forms into multiple, smaller pages with a wizard-like experience. To define a multipage pattern in Routegy, do the following:
- Set top-level
type
property towizard
ormultipage
- Define pages of your pattern as top level properties - every page is an object that can contain element and field set.
TIP
Conditional fields within a wizard must be fully qualified with the page they belong to (E.g. step_one.prop
) .
The following sample is scaffolding for a three-page pattern (all pages are empty).
type: wizard
page_1:
# Page 1 definition
page_2:
# Page 2 definition
page_3:
# Page 3 definition
By default, navigation buttons are captioned as Next
, Back
, and Submit
. Captions can be customized using the buttonCaptions
property inside appSettings
:
appSettings:
buttonCaptions:
next: Forward
back: Previous
submit: Send
Below is a complete example for a printer problem pattern that consists of three pages:
- Problem page with a list of radio buttons representing common problems
- Details page with a text input for collecting more details about the problem
- Follow-up page with an option to opt into email or text updates on the problem
type: wizard
problem_page:
problem:
type: radios
label: What is going on?
items:
- No paper
- No toner
- Printer not responding
- Printer stuck
- Something else
details_page:
details:
type: textarea
placeholder: E.g. printer shows error E122
label: Any more details?
follow_up_page:
how_to_contact:
type: radios
items:
- value: by_email
label: 'Yes, send me an email'
- value: by_phone
label: 'Yes, send me a text message'
- value: no_contact
label: 'No, thanks'
label: Would you like to recieve updates on this?
email:
type: email
placeholder: E.g. me@example.com
label: You email address
visible:
how_to_contact: by_email
phone:
type: phone
placeholder: 'E.g, 555-555-5555'
label: You phone number
visible:
follow_up_page.how_to_contact: by_phone



# Instant events
A pattern of type: instant
will create an event immediately upon interaction with an associated app. The pattern can define the custom branding and result message; it simply does not define any data to collect and thus does not render a form or UI.
This can be helpful for basic help requests (E.g. Assistance needed!) or notifications (E.g. Someone is using this asset now).
type: instant
appSettings:
logo:
>-
https://routegy-assets.s3.us-west-2.amazonaws.com/routegy/schemas/mock-approval-logo.svg
colors:
header: "#2e1046"
headerText: "#eff0eb"
footer: "#eff0eb"
white: "#2e1046"
black: "#eff0eb"
successMessage: Thanks for the report!
# Application settings
In addition to the information about components and their layout, pattern can contain application-level settings like custom colors, header logo, button captions, and a post-submit success message.
TIP
These visual features are not visible when the pattern is edited and previewed in the Routegy admin app (opens new window). They will take effect when a pattern is associated with an app, and can be seen when the app is launched. We suggest opening the app in a separate tab and refreshing as you make changes to the pattern.
App customizations can be defined using a top level appSettings
object that supports the following properties:
Property name | Description | Default |
---|---|---|
logo | Path to a custom logo to be displayed at the top of the app header | No logo |
successMessage | Message to be displayed after interaction with an app has been successfully completed. Markdown (opens new window) is supported. | # Thank you! { .m-0 align=center } |
buttonCaptions | Custom captions for built-in navigation buttons. This includes the Submit button as well as Next and Back buttons used in the wizard/multipage patterns | Submit, Next, and Back |
colors | Custom colors for various elements of an app that will override default Routegy brand colors. | Please see the custom colors section |
# Example
Here is an example pattern that demonstrates some of these customizations including a custom app logo, submit button caption, and selected colors.
appSettings:
logo: https://routegy-assets.s3.us-west-2.amazonaws.com/routegy/schemas/mock-room-help-logo.svg
colors:
header: black
headerText: '#00fab3'
black: black
footer: black
grey: grey
primary: '#007252'
lightGrey: lightgrey
white: white
success: '#00b682'
buttonText: white
buttonCaptions:
submit: Report
problem:
type: radios
label: What is the problem?
items:
- Call quality is poor
- WiFi signal is poor
- Projector/TV not working
- Missing A/V adapters
- Something else
additional_comment:
type: textarea
label: Something else or more details?
placeholder: Provide additional information here
A screenshot of the app showing all of these customizations in effect is shown below.

# Custom color reference
Below is a list of customizable colors along with their default values. When overriding a color, any valid CSS color notation (opens new window) can be used.
Name | Description | Default |
---|---|---|
header | App header background color | |
headerText | App header text color used for app name and description text displayed in the app header | |
footer | App footer background color | |
white | Background color for contents of an app rendered between the header and the footer | |
black | Color used for static text like labels as well as text entered into input elements | |
grey | Secondary color used for visual elements like outlines of checkboxes and radio buttons | |
lightGrey | Secondary color used for borders of various input elements when they are not active (not focused) | |
primary | Color used for borders of active (focused) input elements, hover color for radio and checkbox labels, and fill color for radios, checkboxes, and dropdown arrows | |
buttonText | Text color for buttons | |
success | Background color for elements associated with success actions and notifications (E.g. application submit button) | |
warning | Background color for elements associated with warning notifications | |
danger | Background color for elements associated with danger notifications (E.g. error messages) | |
info | Background color for elements associated with info notifications (E.g. next button in wizards) |