> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Text Field
> Single or multi-line text input for names, descriptions, and IDs
The Text field is the most versatile field type in Penbox. It captures single-line or multi-line text input, making it ideal for names, addresses, descriptions, notes, IDs, and any other free-form text data.
Text fields can be configured with character limits, validation patterns, and placeholder hints. They support both simple input (like a name) and complex multi-line content (like detailed notes or descriptions).
## When to Use
**Use Text fields for:**
* Names (person, company, product)
* Addresses (street, city, full address)
* Descriptions and notes
* IDs and reference numbers
* Email addresses (simple text, or use Email element in forms)
* Phone numbers (simple text, or use Phone element in forms)
* URLs and website addresses
* Comments and feedback
* Any free-form text input
**Consider alternatives:**
* Use **Number** for numeric values (enables calculations)
* Use **Date** for dates (enables date-based features)
* Use **Choices** for predefined options (ensures consistency)
## Configuration Options
| Option | Description | Type | Default | Example |
| ------------- | ------------------------------ | ------- | ---------------- | ---------------------------- |
| `key` | Unique identifier | String | Required | `company_name` |
| `name` | Display label | String | Required | "Company Name" |
| `description` | Help text for users | String | Optional | "Legal name of your company" |
| `multiline` | Enable multi-line textarea | Boolean | `false` | `true` |
| `maxlength` | Maximum character count | Number | None | `500` |
| `pattern` | Regex validation pattern | String | None | `^[A-Z0-9]+$` |
| `placeholder` | Hint text shown in empty field | String | None | "Enter company name" |
| `visibility` | Display setting | String | `always-visible` | `hide-when-empty` |
| `section` | Section this field belongs to | String | None | Section UUID |
## Examples
### Basic Single-Line Text
Collect a company name:
```json theme={null}
{
"key": "company_name",
"type": "text",
"name": "Company Name",
"description": "Official registered name of your company"
}
```
### Multi-Line Text (Notes)
Collect detailed notes or descriptions:
```json theme={null}
{
"key": "claim_description",
"type": "text",
"name": "Claim Description",
"description": "Provide detailed description of the incident",
"multiline": true,
"maxlength": 2000,
"placeholder": "Describe what happened, when it occurred, and any relevant details..."
}
```
### Validated Text (IBAN)
Collect structured text with validation:
```json theme={null}
{
"key": "iban",
"type": "text",
"name": "IBAN",
"description": "International Bank Account Number",
"pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]+$",
"placeholder": "BE68539007547034"
}
```
### Hidden Text Field (System Use)
Store data not shown to users:
```json theme={null}
{
"key": "external_crm_id",
"type": "text",
"name": "CRM ID",
"description": "External system identifier",
"visibility": "always-hide"
}
```
## Validation
Text fields support several validation mechanisms:
### Character Length
Use `maxlength` to limit input:
* Prevents overly long entries
* Ensures data fits in external systems
* Useful for regulated fields with character limits
```json theme={null}
{
"maxlength": 500
}
```
### Pattern Matching
Use `pattern` for regex validation:
* Format validation (IBANs, postal codes, IDs)
* Character restrictions (alphanumeric only)
* Structure enforcement
**Common patterns:**
| Use Case | Pattern | Example |
| ----------------- | ----------------------------- | ----------------------------------------- |
| Alphanumeric only | `^[A-Z0-9]+$` | ABC123 |
| Email format | `^[^\s@]+@[^\s@]+\.[^\s@]+$` | [user@domain.com](mailto:user@domain.com) |
| Phone (simple) | `^\+?[0-9\s\-\(\)]+$` | +1 (555) 123-4567 |
| Postal code (BE) | `^[0-9]{4}$` | 1000 |
| IBAN | `^[A-Z]{2}[0-9]{2}[A-Z0-9]+$` | BE68539007547034 |
Pattern validation only applies when users fill the field. It doesn't validate
existing data or data from API imports.
## Best Practices
**Use descriptive names:**
* "Company Legal Name" is better than "Name"
* "Incident Description" is better than "Description"
* Clear names help users and Intelligence understand what's expected
**Add help text:**
* Use the `description` field to guide users
* Explain format requirements, especially for validated fields
* Mention if the field is required for compliance
**Choose single vs multi-line appropriately:**
* Single-line for short, structured text (names, IDs, codes)
* Multi-line for longer content (descriptions, notes, comments)
* Set appropriate `maxlength` for multi-line to prevent excessive input
**Use validation wisely:**
* Only validate when necessary (IBANs, IDs, codes)
* Don't over-validate (strict patterns can frustrate users)
* Test patterns thoroughly before deploying
**Consider visibility:**
* Use "hide when empty" for optional supplementary fields
* Use "always hide" for system IDs and technical data
* Keep essential fields always visible
***
## Related Field Types
Use for numeric values that need calculations
Use when input should be from predefined options
Use for date values to enable date-based features
Back to Data Schema overview