Add a Clickable Link to an XLSForm Label or Hint
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.
How do I add a link to a question label?
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:
| type | name | label |
|---|---|---|
| note | consent_info | Read the [participant information sheet](https://www.example.org/study/information-sheet) to the respondent before you start. |
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 withwww.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.
Can I put a link in a hint?
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:
| type | name | label | hint |
|---|---|---|---|
| decimal | muac_cm | Mid-upper arm circumference in cm | Not sure how to measure? [Open the MUAC guide](https://www.example.org/guides/muac) |
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.
How do I show a link as a button?
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:
| type | name | label | appearance | default |
|---|---|---|---|---|
| text | helpdesk_link | Field team helpdesk | url | https://www.example.org/helpdesk |
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.
How do I build a link from an earlier answer?
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:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| geopoint | clinic_gps | Record the clinic location | ||
| text | clinic_map | Open the clinic location in Google Maps | url | concat('https://www.google.com/maps/search/?api=1&query=', selected-at(${clinic_gps}, 0), ',', selected-at(${clinic_gps}, 1)) |
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().
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.
Can the link text stay as words when the address is dynamic?
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:
| type | name | label | calculation |
|---|---|---|---|
| text | hh_id | Household ID | |
| calculate | case_url | concat('https://www.example.org/cases/', ${hh_id}) | |
| note | case_link | [Open the case file for ${hh_id}](${case_url}) |
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:
| type | name | label |
|---|---|---|
| note | escalation | Adverse event? [Call the study nurse](tel:+8801700000000) or [email the study team](mailto:[email protected]) before you continue. |
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.
How do I add a link in a form with several languages?
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:
| type | name | label::English (en) | label::Bangla (bn) |
|---|---|---|---|
| note | rights_info | Read the [respondent rights leaflet](https://www.example.org/rights/en) aloud. | [উত্তরদাতার অধিকার লিফলেট](https://www.example.org/rights/bn) পড়ে শোনান। |
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.
Common link mistakes and how to fix them
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 wrote | Write instead | What 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 label | Wrap it: [field manual](https://www.example.org/manual) | No error. The address shows as plain text |
An HTML anchor tag, a href, in the label | The Markdown link | No 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 name | Could not find the name 'case_urll' |
hyperlink or url in the type column | text in type, url in appearance | Unknown question type 'hyperlink' |
concat(https://www.example.org/cases/, ${hh_id}) | Put the fixed text in straight single quotes | Couldn'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 calculation | Add the address in default | No error. The button has no address to open |
| A dynamic Markdown link in a web form | text with the url appearance and a calculation | No error. The link is broken in Enketo |
For other messages, see common XLSForm errors, or paste your form into the free XLSForm validator.
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:
| Platform | Inline link in a label | Notes |
|---|---|---|
| ODK Collect | [text](address) in label or hint | Opens in the phone's browser. Dynamic addresses with ${field} work |
| ODK web forms (Enketo) | Same | Opens in a new tab. Dynamic Markdown links do not work; use the url appearance |
| KoboToolbox Formbuilder | Type the same Markdown into the question label | Web forms run on Enketo, so the Enketo limits apply. No links in guidance hints |
| KoboToolbox (XLSForm upload) | Same as ODK | KoboCollect behaves like ODK Collect |
| SurveyCTO | Labels are formatted with HTML, not Markdown | SurveyCTO'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.
When is a link the right choice?
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.
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.
Next: the XLSForm appearance column →
Frequently Asked Questions
How do I add a hyperlink to an XLSForm label?
Write the link text in square brackets followed at once by the full address in round brackets, inside the label cell. Leave no space between the two brackets and start the address with https. The same text works in the hint column, in ODK and KoboToolbox.
Why does my link show as plain text in the form?
Usually there is a space, or an invisible pasted character, between the closing square bracket and the opening round bracket. Delete the cell and type the link by hand. Also check that the address starts with https and that the label is not in a guidance hint or a choice label.
How do I make a link from an answer in the form?
Add a text question with url in the appearance column and build the address in its calculation column with concat(), joining the fixed part in single quotes to the field reference. This URL widget works in ODK Collect and in Enketo web forms, including KoboToolbox.
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.
Can I make a phone number clickable in ODK Collect?
Yes. Write a Markdown link whose address starts with tel: followed by the number, with the country code. Tapping it opens the phone's dialler with the number filled in. An address that starts with mailto: opens a new email in the same way.
Do links in a form work offline?
The link is still shown and can be tapped, but the page it points to needs an internet connection to load. Put anything the interview depends on, such as consent text or a measuring diagram, in the form itself as a note or an image, and use links for extras.
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.