The appearance column in rtSurvey allows you to customize the visual presentation and behavior of questions in your surveys. This feature enhances user experience and can significantly improve data collection efficiency. rtSurvey supports standard XLSForm appearance attributes and extends them with additional options.

Standard XLSForm Appearance Attributes

rtSurvey supports the following standard XLSForm appearance attributes:

Best Practices for Using Appearance

1. Consistency: Use appearance attributes consistently across your survey for a uniform look.
2. Mobile vs. Web: Consider how appearances will render on different devices and platforms.
3. Performance: Be cautious with appearance attributes that might slow down form loading (e.g., table-list for large groups).
4. User Experience: Choose appearances that make data entry easier and more intuitive for respondents.
5. Testing: Always test your form on target devices to ensure appearances work as expected.

Advanced Techniques

Combining Appearances

Some appearance attributes can be combined for more complex layouts:

| type | name | label | appearance |
|------|------|-------|------------|
| select_one options | choice | Select one: | minimal compact |

Dynamic Appearances

rtSurvey allows for dynamic appearance changes based on form logic:

| type | name | label | appearance | relevant |
|------|------|-------|------------|----------|
| text | time | Enter time: | inline-[%H:%M] | ${show_time} = 'yes' |

Mobile App Considerations

• Some appearances (e.g., quick, signature) are specific to mobile devices.
• Test thoroughly on both Android and iOS to ensure consistent behavior.

rtSurvey Extended Appearance Attributes

In addition to standard XLSForm appearances, rtSurvey supports the following platform-specific options:

Data and display control

Group and navigation

Input behaviour

Layout

Widgets

rating_box-fill — colour slots

Accepts 0, 2, or 4 hex colour slots. When no colours are provided the widget uses built-in defaults.

Default colours (when no slots provided):

• Unchecked: border #ffffff, background #ffffff (with -fill)
• Checked: border #fea500, background #fea500 (with -fill)
• Text colours inherit from CSS

Examples:

rating_box-fill-cccccc-04B404

— grey unchecked, green checked (border + fill), text colours inherited.

rating_box-fill-cccccc-04B404-333333-ffffff

— grey unchecked, green checked, dark text unselected, white text selected.

tagging-choices-noshow-v2 — colour slots

Accepts 0 or 5 hex colour slots.

When colours are omitted entirely, the defaults above apply. All 5 slots must be provided together — partial colour lists are not supported for this widget.

Example:

tagging-choices-noshow-v2-cccccc-cccccc-3498db-333333-ffffff

— grey wrapper border, grey chip borders unselected, blue fill selected, dark text unselected, white text selected.

Colour value format (both widgets)

Colour slots must be 6-digit hex codes without the # prefix (e.g. cccccc, 04B404, 3498db). CSS named colours such as grey or blue are not supported and will be ignored, causing the widget to fall back to defaults. Dynamic colours can be provided via colors(expression(...)) or theme variables (__COLOR_THEME_XXX).

API integration

Language switcher

The change_language appearance does not accept colour parameters — any hex values appended after change_language- are ignored by the renderer. Use the CSS theme variables (--accent-color, --primary-color) to customise the button colour.

change_language default('vi')
change_language default('en')

Inline date/time format

For date, time, and datetime fields, you can specify a custom display format using a format string appended to the appearance:

inline-[%d/%m/%Y]
inline-1line-[%d/%m/%Y %H:%M]

Format tokens are the same as format-date() and format-date-time(). See Functions — Date and time functions.

Example:

Inline button layout — display{} and results{}

For question types that render as an inline icon button (date, time, datetime, image, audio, video, file, barcode, geopoint), two appearance modifiers control the button position and post-capture behavior.

display{...} — button position before capture

display{<align>, <size>, <color>}

results{...} — layout and visibility after capture

Inherits display{} settings. Use to move the button or hide elements once a value has been captured.

results{<align>, hide(<element>)}

The widget automatically switches from display{} to results{} layout the moment a value is captured.

Examples:

inline display{right}                                    → icon right of label
inline display{left, large}                              → large icon on the left
inline display{center, large, #FF5500}                   → large orange icon below label
inline display{right} results{left}                      → icon moves left after capture
inline display{right} results{hide(capture)}             → icon disappears after capture
inline display{center} results{hide(capture), hide(filename)}

Known Limitations

• Complex appearances may not render identically across all platforms.
• Some advanced rtSurvey appearances may not be supported in offline mode.

Troubleshooting Appearance Issues

1. Appearance Not Applied: Check for typos in the appearance column.
2. Inconsistent Rendering: Verify compatibility with the question type and platform.
3. Performance Issues: Consider simplifying complex appearances, especially for large surveys.