lucent-laravel/docs/Fields.md

---
gitea: none
include_toc: true
---

# Fields

Fields define the columns of a schema. Each field has a `ui` type that controls both storage and the admin UI component rendered.

## Common Optional Properties

Most fields share these optional properties:

| Property | Description |
|---|---|
| `required` | Whether the field must have a value to save as `published` |
| `nullable` | Allow saving as `null` |
| `help` | Help text shown below the input |
| `default` | Default value when creating a new record |
| `readonly` | Prevent editing from the UI |
| `group` | Tab group this field belongs to |


## Field Types

### text

One-line text input.

**Required:** `name`, `label`

| Property | Description |
|---|---|
| `min` | Minimum character count |
| `max` | Maximum character count |
| `selectOptions` | Array of options. Strings or `[{value, label}]` objects |
| `optionsFrom` | Schema name to load options from |
| `optionsField` | Field from `optionsFrom` to use as the value |
| `optionsSuggest` | Allow typing new values not in the options list |

---

### textarea

Multi-line text input.

**Required:** `name`, `label`

| Property | Description |
|---|---|
| `min` | Minimum character count |
| `max` | Maximum character count |

---

### slug

Slug input. Auto-generates from a source field if left empty.

**Required:** `name`, `label`, `source`

| Property | Description |
|---|---|
| `source` | Field name to generate the slug from |
| `min` | Minimum character count |
| `max` | Maximum character count |

---

### rich

WYSIWYG rich text editor.

**Required:** `name`, `label`

| Property | Description |
|---|---|
| `min` | Minimum character count |
| `max` | Maximum character count |

---

### markdown

Markdown editor.

**Required:** `name`, `label`

| Property | Description |
|---|---|
| `min` | Minimum character count |
| `max` | Maximum character count |

---

### number

Numeric input.

**Required:** `name`, `label`

| Property | Description |
|---|---|
| `decimals` | Number of decimal places. Default: `0` |
| `min` | Minimum value |
| `max` | Maximum value |
| `optionsFrom` | Schema name to load options from |
| `optionsField` | Field from `optionsFrom` to use as the value |
| `optionsSuggest` | Allow typing new values not in the options list |

---

### checkbox

Boolean true/false toggle.

**Required:** `name`, `label`

---

### color

Color picker.

**Required:** `name`, `label`

| Property | Description |
|---|---|
| `selectOptions` | Restrict to a predefined palette |
| `optionsFrom` | Schema name to load options from |
| `optionsField` | Field from `optionsFrom` to use as the value |
| `optionsSuggest` | Allow typing new values not in the options list |

---

### date

Date selector. Stores as a date string.

**Required:** `name`, `label`

| Property | Description |
|---|---|
| `min` | Minimum date |
| `max` | Maximum date |
| `selectOptions` | Predefined date options |
| `optionsFrom` | Schema name to load options from |
| `optionsField` | Field from `optionsFrom` to use as the value |

---

### datetime

Date and time selector. Stores as an ISO 8601 string.

**Required:** `name`, `label`

| Property | Description |
|---|---|
| `min` | Minimum datetime |
| `max` | Maximum datetime |
| `selectOptions` | Predefined datetime options |
| `optionsFrom` | Schema name to load options from |
| `optionsField` | Field from `optionsFrom` to use as the value |

---

### uuid

UUID text field. Stores an arbitrary UUID string. Typically used as a read-only external reference ID.

**Required:** `name`, `label`

---

### json

Raw JSON data field. Accepts either a JSON string or a plain array — both are stored as JSON.

**Required:** `name`, `label`

---

### file

Upload or select files from a files schema. Files can be uploaded directly or browsed from previously uploaded files. Image files (jpeg, png, webp, gif, tiff) automatically get a 300×300 thumbnail generated on upload.

**Required:** `name`, `label`, `collections`

| Property | Description |
|---|---|
| `collections` | Array of file schema names to choose from |
| `mime` | Allowed MIME types e.g. `["image/*"]` |
| `min` | Minimum number of files |
| `max` | Maximum number of files |

---

### reference

Reference records from another collection.

**Required:** `name`, `label`, `collections`

| Property | Description |
|---|---|
| `collections` | Array of collection schema names to reference |
| `min` | Minimum number of references |
| `max` | Maximum number of references |

---

## Example Field

```json
{
  "ui": "text",
  "name": "title",
  "label": "Title",
  "required": true,
  "min": 3,
  "max": 200,
  "help": "The main title of the post"
}
```