---
title: "key-value"
image: "https://adonia.pages.dev/og.png"
version: "next"
---

> Documentation Index
> Fetch the complete documentation index at: https://adonia.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# key-value

<!-- Generated by `pnpm docs:fields` from packages/core/src/schema/fields/key_value.ts. Edit the TSDoc, not this file. -->

Editable map of string pairs, bound to an object attribute (typically a
JSON column).

The pairs are FLAT and both sides are strings — that is the §11.1 row
(`vine.record(vine.string())`), and it is what makes the type safe to
hand an editor that lets a user invent keys. Nested or typed documents
are `F.json`, which validates through the author's own `rules()`.

| | |
| --- | --- |
| Builder | `F.keyValue(attribute: string): KeyValueField` |
| Wire type key | `key-value` |
| Class chain | `KeyValueField` → `Field` |
| Detail projection | `key-value-entry` |
| Column counterpart | — *(not tabulatable)* |

## Example

```ts
import { F } from '@adonia/core'

F.keyValue('meta')
  .label('Metadata')
  .keyLabel('Property')
  .valueLabel('Value')
  .editableKeys()
  .maxPairs(20)
```

## Props

Beyond the shared [field DSL](/reference/fields#the-shared-field-dsl):

| Prop | Declared on | Behaviour |
| --- | --- | --- |
| `keyLabel(text: string): this` | `KeyValueField` | Header of the key column; the client's own wording applies when unset. |
| `valueLabel(text: string): this` | `KeyValueField` | Header of the value column. |
| `addable(enabled = true): this` | `KeyValueField` | Whether the editor offers an "add pair" control (default `true`). `addable(false)` with `editableKeys()` off pins the key set to whatever the record already carries — the shape for a fixed settings map. |
| `deletable(enabled = true): this` | `KeyValueField` | Whether existing pairs may be removed (default `true`). |
| `editableKeys(enabled = true): this` | `KeyValueField` | Whether existing KEYS may be renamed (default `false`). |
| `minPairs(count: number): this` | `KeyValueField` | Minimum number of pairs; compiles to the record's `minLength` (§11.1). |
| `maxPairs(count: number): this` | `KeyValueField` | Maximum number of pairs; compiles to the record's `maxLength` (§11.1). |

## Validation

Vine base: `vine.string()`.

§11.1 mapping: `vine.record(vine.string())` with the declared pair bounds.

Contributed by `KeyValueField.vineSchema()` in `packages/core/src/schema/fields/key_value.ts`. The shared modifiers (`required`, `nullable`, `requiredWhen`, `unique`, optionality) are applied on top by `Field.buildValidation`, and a `rules()` override replaces the base entirely — the validator compiler never branches on the field class.

## Declared in

- `packages/core/src/schema/fields/key_value.ts` — `KeyValueField`

Source: https://adonia.pages.dev/reference/fields/key-value/index.mdx