Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

WCAG best practices - components (low-code)

Label (Text)

Best practices

  • Headings and labels should be clear and non-duplicated – the user should be able to easily recognize what the description refers to.

  • Labels not associated with a field should be set as a paragraph, using the option “Display as paragraph (<p>)”.

Figure 1. Option "Display as paragraph <p>

Label association with field:

  • If the label applies to one component – select that component from the list in the field labelRef. Example: if the label Text7 is to be a description for the field TextField2, then in the WCAG label configuration Text7 the component should be indicated TextField2 as associated.

Figure 2. Association of the GesTextField1 text field with the label

  • If the label applies to multiple components – select the component first or most important in the context of the group. Example: if the postal code consists of two fields of type TextField, the label should be associated with the first one.

Label consistency:

  • The same elements on different pages should have identical labels to maintain consistency of navigation and content from the user's perspective, including for users of screen readers.

Verification method

check ariaLabel and ariaDescription (if filled in)

Text field (TextField)

Best practices

Filling in the label and accessibility attributes (ariaLabel, ariaDescription):

  • Each field should have an assigned label or ariaLabel (if there is no visual label).

  • By default, after adding the component TextField, the properties ariaLabel and ariaDescription are empty – they must be filled in manually. Example: instead of GesTextField1.ariaLabelKey use GesTextField1.label, which will automatically assign the label value to ariaLabel.

Figure 3. Example of filling in ariaLabelKey

Best practices for field descriptions:

Field requiredness

  • Message "required field" may be too general. It is recommended to use specific messages, e.g. "The first name field is required".

Format validation

  • If the field has format validation (e.g. PESEL, NIP), add to ariaDescription the description of requirements, e.g.: &#xNAN;"11 digits required, no spaces or special characters."

Mask

  • If the field has mask → describe in ariaDescription, e.g. which characters are allowed/not allowed.

  • If the field has visibleMask → describe e.g.: &#xNAN;"For the postal code, enter only digits, without a hyphen."

Maximum length

  • If the field has set value maxLength → add to ariaDescription information about the limit, e.g.: &#xNAN;"Up to 30 characters."

Suggester

  • If the field contains suggester (dynamic suggestions) → describe its behavior, e.g.: &#xNAN;"The value may change automatically when an invalid number is entered."

Validator

  • When the validator error message is ambiguous, include in ariaDescription a meaningful description, e.g.: &#xNAN;"The field cannot contain special characters."

Formatter

  • If the field contains formatter → describe how it works, e.g.: &#xNAN;"The text will be automatically converted to uppercase."

Paste restrictions

  • If the field does not allow pasting text → this should be described in ariaDescription, e.g.: &#xNAN;"The field does not support pasting data."

Prefix / suffix

  • If the field contains prefix or suffix (e.g. "+48", "PLN") → add to ariaDescription, e.g.: &#xNAN;"Field preceded by country code +48."

Verification method

check ariaLabel and ariaDescription (if filled in)

Context help (Tooltip)

Best practices

If the tooltip has visibility conditions, make sure they match the conditions of the component to which the tooltip is assigned.

Multiple-choice field (Checkbox) and Checkbox section (CheckboxSection)

Best practices

Filling in ariaLabel and ariaDescription for the Checkbox and CheckboxSection component:

  • By default, after adding the component Checkbox, fields ariaLabel and ariaDescription are empty. The value ariaLabel should be filled in manually – usually it is enough to assign it the value from the field text.

    Example: Replace: GesCheckbox11.ariaLabel → GesCheckbox11.text &#xNAN;(resulting in: ariaLabel = text)

Figure 4. Example of filling in ariaLabel

  • Attribute ariaDescription is not always required, but it is worth adding it in a more complex context, e.g. when the checkbox requires additional explanation.

Checkbox with formatted content (TextContent):

  • If the checkbox is fed with formatted content from the TextContent, remember that screen readers do not read TextContent. Therefore, the text content should also be assigned to ariaLabel, to ensure its accessibility.

Figure 5. Example of filling in ariaLabel for a checkbox fed with content

Verification method

check ariaLabel and ariaDescription (if filled in)

Date field (DatePicker)

Best practices

Filling in ariaLabel and ariaDescription for the DatePicker component:

  • Each field should have an assigned label or ariaLabel (if there is no visual label).

  • By default, after adding the component DatePicker, the properties ariaLabel and ariaDescription are empty. They should be filled in manually or assigned ariaLabel to the component's label key.

    Example: Instead of GesDatePicker1.ariaLabelKey → use GesDatePicker1.label &#xNAN;(resulting in: ariaLabel = label)

Best practices for filling in ariaDescription for date fields:

  • If the field has date selection restrictions (dateRange) → add a description to ariaDescription, e.g.: &#xNAN;“Select a date in the range from 01/01/2020 to 12/31/2030.”

  • If the field has a custom format set (dateFormat) → describe it in ariaDescription, e.g.: &#xNAN;“Date in the format: month–year (MM-YYYY).”

  • If the mask is enabled (autoMask) → it is worth adding information on how automatic filling works, e.g.: &#xNAN;“Enter digits only – the separator will be added automatically.”

Verification method

check ariaLabel and ariaDescription (clear information about data format)check ariaLabel and ariaDescription (if filled in)

Image (Image)

Best practices

Alternative text (imageAlt) for images

  • Every image should have alternative text filled in (imageAlt or imageAltKey in the form file).

Figure 6. Sample imageAltKey in the form source

  • Recommendations:

    • Maximum text length: 80 characters

    • Maintain consistency of style and language of the description with the rest of the interface

  • Empty attribute alt (alt="") should be used only when the image serves a decorative function, e.g.:

    • background

    • content divider line

    • decorative icon without an informational function

  • Informational/Decorative Presentation - In the WCAG section, you can set informational presentation (the image can be focused) or decorative presentation (it cannot be focused and has an empty imageAlt attribute).

  • Image as a link If the image is contained in a link, alt it should contain both a graphic description and information about the function, e.g.: <a href="https://www.bank.com"> <img src="logo-bank.png" alt="XYZ Bank logo – Go to the XYZ Bank homepage"> </a>

  • SVG elements For SVG graphics, you can add the attribute ariaLabel and ariaDescription

(informacje) More: Additional information

Verification method

check alt value on the application

Value selection from list (Combobox)

Best practices

Filling in ariaLabel and ariaDescription for the Combobox component:

  • Every ComboBox component should have an assigned label or ariaLabel (if there is no visual label).

  • By default, after adding the ComboBox, the fields ariaLabel and ariaDescription are empty – they must be filled in manually or assigned ariaLabel to the label key.

    Example: GesCombobox1.ariaLabelKey → GesCombobox1.label &#xNAN;(resulting in: ariaLabel = label)

Alternative text for the default value "Select":

  • In the "Other" (in the ComboBox configuration) you can define alternative text for the default value "Select", which improves accessibility and comprehensibility for users of screen readers.

Figure 7. Alternative text for "Select"

Verification method

check ariaLabel and ariaDescription

Radio group (RadioGroup)/ Tile group (TileGroup)

Best practices

Label and accessibility attributes:

  • Each component should have a label (label) or ariaLabel (if a visual label is not available).

  • By default, after adding the component (ComboBox, RadioGroup, TileGroup), the fields ariaLabel and ariaDescription are empty — they must be filled in manually or assigned ariaLabel to the label key.

RadioGroup:

  • Each option (Radio) should have a unique value (value), to avoid conflicts in form behavior and screen reader errors.

  • RadioGroup may have:

    • one shared tooltip (for the whole group),

    • or separate tooltips for each option, if each requires additional description.

TileGroup:

  • If in the tile content (Tile) an image has been added, you should:

    • add alternative description (alt), which clearly informs about the image content,

    • set alt="" for decorative graphics so that they are not read by screen readers.

Verification method

check ariaLabel and ariaDescription, check alt values if they were added to images

Repeatable section (RepeatableSection)

Best practices

  • The section should have a title (label) or ariaLabel – this ensures that the screen reader correctly identifies its content and context.

  • In the attribute ariaDescription include information about the minimum and maximum number of possible occurrences of the section.

Verification method

check ariaDescription

Slider/Step slider

Best practices

  • By default, after adding the component Slider, the properties ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

  • In the attribute ariaDescription it is worth including information about the range of values that can be selected

Verification method

check ariaDescription

Plus Minus

Best practices

  • By default, after adding a component of type Plus-Minus, the attributes ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

  • In the attribute ariaDescription it is worth adding information about the minimum and maximum possible value, so that screen reader users have clarity about the available range.

Verification method

check ariaDescription

Collapsible formatted content (RollableTextContent)

Best practices

  • Make sure the component has a title (label) and ariaLabel.

  • ariaLabel should clearly describe the content of the component so that screen readers can correctly convey the content information to the user.

Verification method

check title value

Product selection (ProductSelector)

Best practices

  • By default, after adding the component ProductSelector, fields ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

  • Images used in the component ProductSelector should have filled-in values alt — in line with accessibility principles, so that screen readers can correctly describe the graphic.

  • HTML content used in the component (ContentHTML) should be verified using an HTML validation tool (e.g. Markup Validation Service) to eliminate errors and improve accessibility.

Verification method

check alt values and HTML code

Internal link (PageNavigationLink) and external link (Link)

Best practices

  • By default, after adding the link the fields ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

  • Do not use only uppercase letters (caps lock) in link texts, so as not to make them harder to read and recognize for users and screen readers.

  • The user should be informed whether clicking the link will open a new tab or launch another application. This can be achieved by:

    • setting the link opening property, e.g. target="_blank",

    • adding informative text e.g. in the title (title) or in the ariaDescription.

    • a clear graphic or textual designation.

  • In the link properties you can set, among others:

    • opening mode (target, e.g. _blank),

    • text displayed when hovering the cursor over it (attribute title),

    • anchor name (page fragment).

Figure 8. Link component properties

Verification method

check ariaLabel and ariaDescription

Statements

Best practices

In the Properties the following overriding properties for texts displayed in the interface can be changed:

  • Overriding property: "Collapse statement content"

  • Overriding property: "Expand statement content"

  • Content overriding property: "You have not consented to the required statements"

  • Content overriding property: "You have not made a selection for all statements, fill in the required information in the statements section"

  • Content overriding property: "I accept the selected declarations"

  • Content overriding property: "I accept all declarations"

Illustration 9. Properties of the declarations component

Attachments (UploadFile)

Best practices

  • By default, after adding UploadFile fields ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

  • In the attributes

    • By default, after adding the link the fields ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

    or ariaDescription should include information regarding:

    • requirement for attachments,

    • number of files that can be added.

Verification method

ariaLabel check

Map (MapView)

Best practices

  • By default, after adding MapView fields ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

  • In the attribute ariaLabel or ariaDescription it is worth including information important to the user, e.g.:

    • description of the map's purpose,

    • usage instructions (e.g. whether a location can be selected),

    • other relevant accessibility information.

Verification method

ariaLabel check

Data confirmation (ConfirmationSection)

Best practices

  • By default, after adding confirmation section fields ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

  • In the attribute ariaLabel or ariaDescription it is worth including additional information helpful in the context of confirming data, e.g.:

    • instructions for confirmation,

    • information about the need to check the data before approving it.

QR code generator (QRCodeGenerator)

Best practices

By default, after adding QRCodeGenerator fields ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

Verification method

ariaLabel check

QR code scanner (QRCodeScanner)

Best practices

By default, after adding QRCodeScanner fields ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

Verification method

ariaLabel check

AZTEC code scanner (AztecCodeScanner)

Best practices

By default, after adding AztecCodeScanner fields ariaLabel and ariaDescription are empty. They should be filled in manually — especially ariaLabel, if the component does not have a visible label.

Verification method

ariaLabel check

Useful pages

Screen readers

PreviousWCAG best practices - general (low-code)
NextWCAG best practices - print templates (low-code)

Last updated

Was this helpful?