SurveyLoopr
Tips & Tricks
12 min read

Add a Clickable Link to an XLSForm Label or Hint

Mehrab Ali
Mehrab AliPublished November 22, 2026

To add a clickable link to an XLSForm label or hint, write the link text in square brackets and the address in round brackets right after it: [field manual](https://www.example.org/manual). For a link button, or a link built from an earlier answer, use a text question with the url appearance. Every example below compiles with pyxform and ODK Validate, the check ODK Central runs when you upload a form.

Download example form (.xlsx)All seven examples in one XLSForm, one group each. Tested with pyxform and ODK Validate; free to reuse under CC BY 4.0.Download

Type [link text](address) anywhere in the label cell. The words in square brackets are what the enumerator sees and taps. The address in round brackets is where the link goes. Here a consent note links to the participant information sheet:

typenamelabel
noteconsent_infoRead the [participant information sheet](https://www.example.org/study/information-sheet) to the respondent before you start.
surveychoicessettings

Three rules make it work:

  • No space between the brackets. ]( must be typed together.
  • Use the full address. Start with https://. An address that begins with www. is not a complete link.
  • Keep the link text short and specific. "participant information sheet" tells the enumerator what opens. "click here" does not.

In ODK Collect the link opens in the phone's default browser. In web forms it opens in a new browser tab, so the form stays open with its answers.

Yes. The same syntax works in the hint column. A hint is a good place for a link the enumerator needs only sometimes, such as a measuring guide:

typenamelabelhint
decimalmuac_cmMid-upper arm circumference in cmNot sure how to measure? [Open the MUAC guide](https://www.example.org/guides/muac)
surveychoicessettings

Links belong in label and hint. Two places to avoid:

  • guidance_hint. KoboToolbox support has confirmed that links in guidance hints are not made clickable in its web forms.
  • Choice labels. Web forms built on Enketo do not format choice labels, and a tap on a choice selects it. Put the link in the question label or hint, above the choices.

Use a text question with url in the appearance column and the address in the default column. This is ODK's URL widget. It shows the label with a button that opens the address, and it takes no input:

typenamelabelappearancedefault
texthelpdesk_linkField team helpdeskurlhttps://www.example.org/helpdesk
surveychoicessettings

Choose the button over an inline link when the link is the point of the screen: a helpdesk page, a referral directory, a payment portal. It is a bigger target than two words inside a sentence. The appearance column guide covers the other appearances for text questions.

Put the address in the calculation column of the url question and build it with concat(). This example turns a recorded clinic location into a Google Maps link, so a supervisor reviewing the form can open the exact spot:

typenamelabelappearancecalculation
geopointclinic_gpsRecord the clinic location
textclinic_mapOpen the clinic location in Google Mapsurlconcat('https://www.google.com/maps/search/?api=1&query=', selected-at(${clinic_gps}, 0), ',', selected-at(${clinic_gps}, 1))
surveychoicessettings

A geopoint is stored as four numbers separated by spaces: latitude, longitude, altitude and accuracy. selected-at(${clinic_gps}, 0) reads the first and selected-at(${clinic_gps}, 1) the second. See collecting GPS coordinates for the settings that make the reading reliable.

The same pattern works for any address that ends in an ID: a case file, a facility page, a record in your own system. The address can also come from a CSV file with pulldata().

Warning:

A Markdown link whose address is a ${field} reference works in ODK Collect but not in Enketo web forms, which KoboToolbox and ODK Central use. There the link comes out broken. If the form will be filled in a browser, use the url appearance with a calculation instead.

In ODK Collect, yes. Build the address in a calculate row, then use it inside the round brackets. The link text can show an answer too:

typenamelabelcalculation
texthh_idHousehold ID
calculatecase_urlconcat('https://www.example.org/cases/', ${hh_id})
notecase_link[Open the case file for ${hh_id}](${case_url})
surveychoicessettings

This reads better than a button with a long address beside it. Use it only when every device runs ODK Collect. For a team that mixes phones and web forms, keep the url version from the section above.

How do I make a phone number or email address clickable?

Use tel: or mailto: in place of https://. On a phone, a tel: link opens the dialler with the number filled in:

typenamelabel
noteescalationAdverse event? [Call the study nurse](tel:+8801700000000) or [email the study team](mailto:[email protected]) before you continue.
surveychoicessettings

To call a number that was typed into the form, build the link in a calculate row with concat('tel:', ${phone}) and use it as in the case file example. Like every dynamic Markdown link, that version is for ODK Collect.

Type the link in each language column. The link is part of the label text, so each translation carries its own brackets and its own link words, with the same address or a translated page:

typenamelabel::English (en)label::Bangla (bn)
noterights_infoRead the [respondent rights leaflet](https://www.example.org/rights/en) aloud.[উত্তরদাতার অধিকার লিফলেট](https://www.example.org/rights/bn) পড়ে শোনান।
surveychoicessettings

If the link works in one language and shows as plain text in another, retype that cell by hand. A link pasted from Word or a chat app can carry an invisible character or a space between ] and (, and the form then shows the brackets as text. The guide on adding languages to an ODK form covers the column names.

Most link mistakes upload without any error and only show on the device. The messages in the third column are what pyxform and ODK Validate return where there is one:

You wroteWrite insteadWhat you will see
[field manual] (https://www.example.org/manual)Remove the space after ]No error. The brackets and the address show as plain text
[field manual](www.example.org/manual)Start the address with https://No error. The link does not open the page
https://www.example.org/manual typed alone in a labelWrap it: [field manual](https://www.example.org/manual)No error. The address shows as plain text
An HTML anchor tag, a href, in the labelThe Markdown linkNo error. ODK's documentation says HTML that works in Collect does not work in Enketo web forms
[Open the case](${case_urll})Fix the field nameCould not find the name 'case_urll'
hyperlink or url in the type columntext in type, url in appearanceUnknown question type 'hyperlink'
concat(https://www.example.org/cases/, ${hh_id})Put the fixed text in straight single quotesCouldn't understand the expression starting at this point
'https://www.example.org/cases/' + ${hh_id}concat('https://www.example.org/cases/', ${hh_id})No error. + adds numbers, so the address is not built
url appearance with no default or calculationAdd the address in defaultNo error. The button has no address to open
A dynamic Markdown link in a web formtext with the url appearance and a calculationNo error. The link is broken in Enketo

For other messages, see common XLSForm errors, or paste your form into the free XLSForm validator.

Note:

A link needs a connection. Offline, the browser opens and shows an error page, and the enumerator loses time. For anything that must be readable in the field, such as a consent text or a measuring diagram, put it in the form itself as a note or as an image in the question, and keep links for extras.

Does this work the same in ODK, KoboToolbox and SurveyCTO?

The Markdown link is the same text in ODK and KoboToolbox. SurveyCTO formats labels differently:

PlatformInline link in a labelNotes
ODK Collect[text](address) in label or hintOpens in the phone's browser. Dynamic addresses with ${field} work
ODK web forms (Enketo)SameOpens in a new tab. Dynamic Markdown links do not work; use the url appearance
KoboToolbox FormbuilderType the same Markdown into the question labelWeb forms run on Enketo, so the Enketo limits apply. No links in guidance hints
KoboToolbox (XLSForm upload)Same as ODKKoboCollect behaves like ODK Collect
SurveyCTOLabels are formatted with HTML, not MarkdownSurveyCTO's documentation says hints cannot include HTML formatting, so keep links in the label

The url appearance on a text question is documented by ODK and works in Enketo web forms, which covers KoboToolbox. On SurveyCTO, test a link in both SurveyCTO Collect and the web form before fieldwork; the Markdown brackets on this page are not its syntax. For bold, colour and headings in the same labels, see styling text in XLSForm.

A link suits material that is long, changes often, or is needed by a few people: the full protocol, a referral directory, a helpdesk form, a map of the spot a record was taken. The enumerator who needs it taps once, and everyone else never sees more than a few words.

It is the wrong choice for anything the interview depends on. If the respondent must hear a consent statement, write it in the form. If the enumerator must follow a diagram to take a measurement, attach the image. A form should still work when the signal drops.

Keep the address stable. A form in the field for six months will be opened long after a shared-drive link has been reorganised. Link to a page you control, and test every link again before each round of data collection.

Tip:

You can describe the link in plain language instead: "add a note with a link to the field manual, and a button that opens the household's location in Google Maps". LooprAI writes the label, the url question and the concat() calculation, then compiles the form with pyxform before anything is saved, so a missing quote or a misspelled field name never reaches your form.

Build my first form free

Next: the XLSForm appearance column →

Frequently Asked Questions

Do dynamic Markdown links work in KoboToolbox web forms?

No. A Markdown link whose address is a field reference works in ODK Collect and KoboCollect, but Enketo web forms do not build it and the link comes out broken. For forms filled in a browser, use a text question with the url appearance and a calculation.

No Credit Card Required

Build the form first. Add hosting when you need it.

Start free with LooprAI, then deploy a managed ODK Central server or run DataSnap checks when your project is ready.

Automation handles the mechanical work.

Researchers decide what the evidence means.