# Fields

<figure><img src="/files/w6Etx7RYSFKn0FWUHosh" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
This article is quite lengthy. To quickly find the information you're looking for, consider using the search.
{% endhint %}

## Overview <a href="#id-605b2c" id="id-605b2c"></a>

Different types of fields can be used in forms. Each one of them represents a precise type of information to collect. Make sure to use the right field for the right type of information to guide users when filling out a form.

<figure><img src="/files/Vxau9NsCfwx16ybgJ3Em" alt=""><figcaption><p>Decision tree to choose which field to used based on your use case</p></figcaption></figure>

{% hint style="info" %}
We do not recommend using Placeholder text for most of our form fields, as it is not accessible and disappears when users start typing their information. Use `Helptext` instead to convey extra information to help fill in the field. [Learn more about Placeholder text and Helptext](#content)
{% endhint %}

## Text Fields

In the following tabs, you will find all informations for fields containing textual inputs.

{% tabs %}
{% tab title="Text Fields" %}

<figure><img src="/files/DN9WM2xUQHi1At2xo9QI" alt=""><figcaption></figcaption></figure>

`Text Field` is the most basic form element. It provides a single-line, plain-text input control. It should be used when we expect a short answer from users.

We provide multiple optional features to custom the field, such as: `Label`, `Requirement Indicator` (red asterisk), `Tooltip`, `Suffix` or `Prefix`, `Placeholder` and `Helptext.`
{% endtab %}

{% tab title="Text Area Field" %}

<figure><img src="/files/81kOizOeZ6DifvUFGOdd" alt=""><figcaption></figcaption></figure>

`Text Area Field` is different from `Text Field` because it allows users to write more than a single-line answer. This component would be preferred for use cases such as messaging, comments, or descriptions.

It has almost the same options as `Text Field`, including `has counter,`only without `Prefix` and `Suffix` options.&#x20;

It comes in 3 sizes to adapt to each use case : `Small` (72px height), `Default` (96px height) and `Large` (300px height).

If needed, users can interact with the field at its bottom-right corner to expand it.
{% endtab %}

{% tab title="Email Field" %}

<figure><img src="/files/hU5uqagBAXpumOuO0vAY" alt=""><figcaption></figcaption></figure>

`Email Field` is a specific form element. **It must only be used to provide mail information.** This field cannot be used to collect other information than mail. This component is subject to a technical format validation: users will have to enter a mail format to validate this field. Otherwise, the field will be in an error state.

A mail icon helps users differentiate this specific field from any other field. It is automatically included in the component and cannot be removed.

Like `Text Field`, optional features are available to custom the field only without `Prefix` and `Suffix` options.
{% endtab %}

{% tab title="Password Field" %}

<figure><img src="/files/5mp6Hxx27rRbfrvQEZdZ" alt=""><figcaption></figcaption></figure>

The `Password Field` is dedicated **exclusively to handling passwords** and should not be repurposed for other use cases. This component includes crucial security features and behaviors.

The 'Show/Hide' functionality, triggered by clicking the eye icon, allows users to reveal or hide the password. This feature is integral to the component and cannot be removed.

Additionally, to provide higher security if needed, another props called 'hidePasswordVisibilityButton' allows control of  preview button's visibility :

* During creation, the preview button is displayed.
* When editing, the preview button is hidden, a placeholder value in the field indicate the field has a value saved. But if the field goes on focus, the value is cleared and redisplay the preview button.
  {% endtab %}
  {% endtabs %}

## Number Fields <a href="#id-350e09" id="id-350e09"></a>

In the following tabs, you will find all informations for fields containing inputs with numbers.

{% tabs %}
{% tab title="Float Number Field" %}

<figure><img src="/files/06CIgZlnZ7wShwsOVqbj" alt=""><figcaption></figcaption></figure>

`Float Number Field` is a specific form element that only accepts numeric inputs. It can be used for use cases such as percentages, measurement, and delays.

**Do not use this component for monetary information**, use dedicated `Monetary Field`

Use Prefix props (`Select` or `String` Prefix) to indicate the expected unit for user input.

<figure><img src="/files/v7N4taXpUOlanIzwW1mO" alt=""><figcaption></figcaption></figure>

* `Select Prefix` : allow users to choose a unit between at least two options.
* `String Prefix` : visual help to understand which unit number is required. Users cannot change it.

Number formatting is automatically defined by the user's locale. It helps for auto-formatting while OnBlur (decimal, thousand, separator).
{% endtab %}

{% tab title="Integer Number Field" %}

<figure><img src="/files/vxLNjf24ba1Z41KhVjVl" alt=""><figcaption></figcaption></figure>

`Integer Number Field` is a specific form element that **only accepts whole number inputs**. While it can be positive or negative numbers, **it just cannot allow separators**. It can be used for use cases such as delays and stocks.

While this field has the same optional features as other fields, it also automatically comes with a `Stepper Control` to allow quick small adjustments. In this field, users can use their keyboard to increase/decrease value

The valid input range of an `Integer Number Field` can be set by defining minimum and maximum values. In this case, use `helptext` to provide information about the range.
{% endtab %}

{% tab title="Monetary Field" %}

<figure><img src="/files/8RS2PvXrKRBRSA3b976e" alt=""><figcaption></figcaption></figure>

`Monetary Field` is a specific form element that only accepts numeric inputs. It does allow separators. This field can only be used for monetary use cases such as setting a price or a price reduction.

Like `Float Number Field`, this field also comes with `Prefix` features:

* `Select Prefix` : allow users to choose a unit between at least two options.
* `String Prefix` : visual help to understand which unit number is required; users cannot change it.

Another customization option is available: `currencyDisplay` which allows defining which code of the currency is displayed in the field:

* 'symbol' : $US
* 'code' : USD
* 'name' : U.S Dollar
* 'narrowSymbol' : $

⚠️ Number format and currency are automatically defined by user local.
{% endtab %}
{% endtabs %}

## Upload Field <a href="#id-31923f" id="id-31923f"></a>

<figure><img src="/files/T9G6Xv9OvrsP9er5xLEu" alt=""><figcaption><p>Upload Field with or without dropzone</p></figcaption></figure>

`Upload Field` is a specific form element that allows users to upload a file to the platform.

This field is different from others because users cannot actually enter any kind of text into it. This field can only be used to retrieve a file from users' computers. It can be used for use cases such as providing ID documents, company logos, and product pictures...

{% hint style="warning" %}
This component allows users to **upload** a file from the platform, not to download one. To download any kind of document from the platform, refer to [`File Download Component`](/design/components/actions/file-download.md), a dedicated component to be used in a form.
{% endhint %}

{% tabs %}
{% tab title="File Upload" %}
`FileUpload` is a component attached to `Upload Field`. When a file is selected, we display `FileUpload` component under the button.

If the project allows several files, `FileUpload` components are stacked.

<figure><img src="https://zeroheight.com/uploads/C5XhkQTnYlbLozNqUelKMA.svg" alt=""><figcaption><p>Behavior when several files are accepted : FileUpload components are stacked</p></figcaption></figure>

If the project does not allow several files, the button becomes disabled after selecting one file. If users remove the file by clicking on its "Close icon", then the component comes back to its initial state.

<figure><img src="https://zeroheight.com/uploads/1JsZhamn67xLfq4pcVR6vg.svg" alt=""><figcaption><p>Behavior when only one file is accepted : Button is disabled</p></figcaption></figure>
{% endtab %}

{% tab title="Dropzone" %}
Each project can choose to use the `dropzone`.

`Dropzone` comes with error management to give direct feedback to users if files do not comply with defined rules (maximum size, format...)

<figure><img src="https://zeroheight.com/uploads/yB_Bhr57KF_4QLJQC9or8w.svg" alt=""><figcaption><p>Exemples of error management</p></figcaption></figure>
{% endtab %}
{% endtabs %}

## Layout <a href="#id-20893a" id="id-20893a"></a>

For a clear form layout, follow these simple design rules:&#x20;

* Place inputs in a vertical sequence, each stretching across the full panel width for a clean look.&#x20;
* If you're aligning inputs side-by-side, leave a 16px gap between them to prevent clutter.&#x20;
* Similarly, when stacking inputs vertically under a single label, keep a 16px space for clear separation.&#x20;

## Content

<figure><img src="https://zeroheight.com/uploads/2WjnZ7L3QnZyK0vnGj3pkQ.png" alt="" width="375"><figcaption></figcaption></figure>

### Label <a href="#id-84d0a0" id="id-84d0a0"></a>

**Use a noun**, no preposition/article (my/a/the), and no action verb.

{% hint style="info" %}
**Template**: \<Noun>
{% endhint %}

### Help text <a href="#id-77a6a9" id="id-77a6a9"></a>

Prefer a help text over a tooltip to add extra details, and explain how to fill the field or its purpose.

If you feel you're repeating yourself in the help text, you don't need it.

{% hint style="info" %}
**Template:** \<Optional sentence giving extra information on how this content will be used or why it's important.>
{% endhint %}

### Placeholder text <a href="#id-88b593" id="id-88b593"></a>

As they disappear when you start typing, **refrain from using placeholders** if possible. Rely on a clear label and help text.

### Tooltip <a href="#id-4902f6" id="id-4902f6"></a>

Tooltip appears when hovering the ? icon or a disabled button. They are not used to communicate critical information but to provide additional information.

{% hint style="info" %}
**Template**: \<Extra info in one sentence, not critical info but additional guidance. Did you know?>
{% endhint %}

## Key takeaways <a href="#id-8864e6" id="id-8864e6"></a>

{% hint style="success" %}

* Use wisely different features for field customization (placeholder, tooltip, requirement level...)
* Use Float Number Field with a prefix for percentages
* Use predictable and logically ordered values
  {% endhint %}

{% hint style="danger" %}

* Never use Password Field with a placeholder and no label
* Never use Monetary field for any other means than money
* Create new/custom behavior patterns with form components
  {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://design.mirakl.com/design/components/form/fields.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.