Form controls guidelines

---

Labels

Avoid long labels, but don't sacrifice clarity. If needed, put additional information in help text and tooltips.

Version

Use the `major.minor` format. You can use wildcards `*` to span over multiple versions.

Do: Say what the field is in the label. Use help text for additional information.

Numeric version (e.g. `2.*`)

Don't: Put everything in the label. It's hard to scan.

Hint text

Place hints and instructions outside a text field so it is always visible to the user. Keep the hint text short, maximum two sentences long. Use hint text to:

• Explain why you are asking a certain question: "We will only email you if there is a problem with your order."
• Provide clarifying details on what to type: "Enter the full 32-character ID."
• Tell the user where to find the information you're asking for: "Find the Elasticsearch cluster ID on the main administration page of your deployment."

Timeout

Use shorthand notation, such as 30s, 10m, or 1h.

Do: Help users make the right decision by clarifying what goes inside a field.

Name

This is the name that will be visible to other users.

Do: Use complete sentences and ending punctuation.

Placeholder text

In fields

Use the placeholder property to describe the expected value of the input or to provide a useful example.

Phone number

Include the international call prefix.

Do: Provide a simple example that highlights the expected syntax or value.

Endpoint

Include the port number.

Don't: Start with `for example`, or `e.g.`.

Add placeholder text in addition to field labels and help text, not as a replacement. Omit it if it doesn't add value for users. And keep it short.

Source

Enter a valid IP address.

Do: Place info essential to completing the form outside the field so that it is always visible.

Source

Enter CIDR or IP address. For example, `192.168.132.6/22`.

Don't: Use text that adds no value, such as “Type here”.

Do: When space is limited and the UI is very simple, you can use field labels as placeholder text. This must stay an exception.

Key

Value

Do: If space allows it, prefer following the rule described earlier with labels outside of the fields.

In search bars

In a search bar, be specific about what users can enter.

Do: Give users a hint at things they might want to search for. State the action the user performs (find, search) instead of the field functionality (jump to).

Don't: Use an ellipsis.