CynosureComponents / Controls
KeyValueEditor
Editable key and value pairs, such as HTTP headers or environment variables, in rows or as text.
When to useLink to "When to use"
- A list of named values people add to, edit, reorder and switch off: headers, query parameters, metadata.
Use something else when:
- the keys are fixed: a form of TextFields
- the values are short tags without keys: TagInput
- the pairs are only shown: DescriptionList
UsageLink to "Usage"
import { KeyValueEditor, type KeyValuePair } from "@arshad-shah/cynosure";
<KeyValueEditor label="Headers" pairs={headers} onChange={setHeaders} />Each pair is { id, key, value, enabled?, secret? }. Give new pairs from your data a stable id; pairs added in the editor get one of their own. secret: true masks the value.
"Edit as text" turns every pair into a key: value line (with # in front of a pair that is switched off), so a block of headers can be pasted in at once.
Files as valuesLink to "Files as values"
For multipart form fields, allowFiles adds a button to each row that picks a file for its value (accept limits the types). The pair gets file, and value holds the file's name.
<KeyValueEditor label="Form fields" pairs={fields} onChange={setFields} allowFiles accept="image/*" />PropsLink to "Props"
| Prop | What it does | Type | Default |
|---|---|---|---|
labelRequired | What the pairs are ("Headers", "Query parameters"). Names the list and the text view. | string | |
pairs | The pairs, when you control them. | KeyValuePair[] | |
defaultPairs | Starting pairs when uncontrolled. | KeyValuePair[] | |
onChange | Called with the full list after each change: an edit, a row added, removed, moved or switched off. | ((pairs: KeyValuePair[]) => void) | |
toggleable | A checkbox per row to switch it off without deleting it. Default true. | boolean | true |
bulkEdit | A toggle to edit every pair as key: value lines (paste a block of headers). Default true. | boolean | true |
allowFiles | A button per row to make its value a file instead of text (multipart form fields). accept limits the types. | boolean | |
accept | File types for allowFiles, as for <input accept>. | string | |
disabled | Turns off every field and button. | boolean | |
size | Size of the fields and buttons. Default "md". | Size | "md" |
labels | Replace the built-in English text. | Partial<KeyValueEditorLabels> | |
className | Added to the root element, for layout. | string | |
style | Layout only. Restyle through --cy-key-value-editor-* tokens. | CSSProperties |
Generated from the type definitions in @arshad-shah/cynosure 0.5.0.
Behaviour and accessibilityLink to "Behaviour and accessibility"
- Names: every field is named for its row ("Value (Authorization)"), and so are the checkbox ("Use Authorization") and the remove button ("Remove Authorization").
- Reordering: drag a row's grip, or focus it and press Space, the arrows, then Space (Escape cancels); moves are announced.
- Focus: Add focuses the new row's key field; removing a row focuses the row that took its place, or Add.
- Touch: grips and buttons have 44px hit areas on touch screens.
ThemingLink to "Theming"
Token: --cy-key-value-editor-gap. Rows, fields and buttons follow the SortableList, TextField and Button tokens.
RelatedLink to "Related"
These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.