# Inline edit

- Entry point: `@koobiq/components/inline-edit`
- NgModule: `KbqInlineEditModule`
- API: https://koobiq.io/api/inline-edit.md
- Component tokens: https://koobiq.io/tokens/inline-edit.md
- Page: https://koobiq.io/en/components/inline-edit/overview

## Overview

Inline editing can replace a traditional form when the user only needs to update a few fields among many available parameters.

### Vertical list

[**Example: Inline edit vertical list** (`inline-edit-vertical-list`)](https://koobiq.io/examples/inline-edit-vertical-list.md)

### Horizontal list

In a horizontal list, you can adjust the column width of the parameter name and set it to either a fixed or relative value.

[**Example: Inline edit horizontal list** (`inline-edit-horizontal-list`)](https://koobiq.io/examples/inline-edit-horizontal-list.md)

### Without labels

[**Example: Inline edit without label** (`inline-edit-without-label`)](https://koobiq.io/examples/inline-edit-without-label.md)

### Input controls

[**Example: Inline edit controls** (`inline-edit-controls`)](https://koobiq.io/examples/inline-edit-controls.md)

### Empty state

Parameters should never appear as blank in view mode. Instead, use placeholder text to signal that a field can be edited.

By default, the system displays _“Not filled”_, but it’s better to use contextual messages for clarity. For example: _Responsible: Not assigned_, _End date: Not specified_.

For fields without labels, the placeholder can include the field name, e.g., _Description: Not provided_, _Operator: Not set_, _Incident type: Not defined_.

[**Example: Inline edit unfilled** (`inline-edit-unfilled`)](https://koobiq.io/examples/inline-edit-unfilled.md)

### Validation

Exiting edit mode attempts to save changes. An invalid value is never written through: the editor stays open and the field is highlighted, while focus stays wherever the interaction left it.

The error message is opt-in. Pass `validationTooltip` to get the red tooltip the example below shows — without it nothing is displayed, and a `kbq-error` inside the form field is the alternative. `showTooltipOnError` switches the tooltip off again without dropping the message.

Validation is run against the control itself rather than against its error styling, so a value the user never touched is rejected as well — a select that commits from `(selectionChange)` cannot write an invalid option through.

[**Example: Inline edit validation** (`inline-edit-validation`)](https://koobiq.io/examples/inline-edit-validation.md)

When certain characters are always invalid (e.g., letters in an IP address), block their input directly. Prevented characters do not appear, and a yellow tooltip explains why.

If the user clears a value, you can substitute either a default value or the last valid entry to avoid errors.

### Saving to a server

The component owns the loading state: it closes the editor, keeps the timings, updates its own status and remembers the last saved value. Connect the stream of the request to the `saveHandler` property for that.

View mode renders the control's value: the editor closes before the server answers.

If the value still equals the one the editor opened with, no request is sent. `compareWith` decides that: the default compares with `===`, which suits text and numbers, so bind your own for arrays and objects, or `null` to send every time. A failed save is always retried.

The request outlives the field — removing the row doesn't cancel it. Provide `KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER` in the root injector if a failure has to be reported after that, because the `saveError` output goes away with the view.

#### Loading state

If the server responds within 100 ms, don't show a loading indicator. Otherwise, the field in view mode switches to the Progress state for at least 300 ms to avoid flickering. Edit mode cannot be reopened while the request is in flight.

[**Example: Inline edit save progress** (`inline-edit-save-progress`)](https://koobiq.io/examples/inline-edit-save-progress.md)

#### Save error

The value's background turns into the error color and stays that way until the user reacts. The entered value is kept in the field.

The message is shown by the application: set the shared reaction with the `KBQ_INLINE_EDIT_SAVE_ERROR_HANDLER` token, override it for a single field with the `saveErrorHandler` property, or subscribe to the field's `saveError` output. The handler receives the error and the field itself, with its `retrySave()`, `toggleMode()` and `rollback()` actions.

The message doesn't hide on a timeout, and closing or dismissing it discards the unsaved value.

Cancelling the editor doesn't clear the failed state: the value is still the one the server refused, so the field stays marked until the save succeeds or `rollback()` discards it.

[**Example: Inline edit save error** (`inline-edit-save-error`)](https://koobiq.io/examples/inline-edit-save-error.md)

When the server rejects part of the value rather than all of it, match the rejected items against what view mode shows and mark only those.

[**Example: Inline edit save invalid items** (`inline-edit-save-invalid-items`)](https://koobiq.io/examples/inline-edit-save-invalid-items.md)

### Action menu

On hover or focus, an action button or menu can appear on the right side of the field: copy text, add value to filter, clear field, fill from template.

These actions are visually separated from the main value and placed in the top-right corner. When the menu is open, both the highlight and the icon remain visible.

[**Example: Inline edit menu** (`inline-edit-menu`)](https://koobiq.io/examples/inline-edit-menu.md)

### Switching modes

The editor can be opened and closed programmatically: bind `[(mode)]` and set it to `'edit'` or `'view'`.

### Usage examples

#### Editable header

[**Example: Inline edit editable header** (`inline-edit-editable-header`)](https://koobiq.io/examples/inline-edit-editable-header.md)

#### Content alignment

Inline-editable elements should remain aligned with their appearance in view mode. Do not account for extra padding or spacing that may appear when the element is hovered, focused, or in edit mode.

[**Example: Inline edit content alignment** (`inline-edit-content-alignment`)](https://koobiq.io/examples/inline-edit-content-alignment.md)

#### Custom design

[**Example: Inline edit customized design** (`inline-edit-customized-design`)](https://koobiq.io/examples/inline-edit-customized-design.md)

#### Select-style editor

On selection, open only the dropdown menu — don't show a bordered input field like Select's. The field doesn't need a border of its own, the dropdown alone is enough.

[**Example: Inline edit select basic** (`inline-edit-select-basic`)](https://koobiq.io/examples/inline-edit-select-basic.md)

After picking an option, the field returns to view mode.

#### Multiline field

Sometimes it's worth making the dropdown options multiline. It's recommended to match the dropdown's width to the field's width.

[**Example: Inline edit select multiline** (`inline-edit-select-multiline`)](https://koobiq.io/examples/inline-edit-select-multiline.md)

#### Reset

Place the clear element inside the dropdown menu — since the select field itself isn't visible, there's no other suitable place for a reset button.

Also recommended: add an option whose label makes it clear that no value is set. This echoes the wording used for the empty field in view mode.

[**Example: Inline edit select** (`inline-edit-select`)](https://koobiq.io/examples/inline-edit-select.md)

After picking an option, the field returns to view mode.

### Keyboard

The field is a single tab stop.

| Key                | Mode                      | What it does                                                          |
| ------------------ | ------------------------- | --------------------------------------------------------------------- |
| Enter / Space      | View                      | Open the editor                                                       |
| Enter              | Edit                      | Saves the value and returns the field to view mode, except on buttons |
| Esc                | Edit                      | Closes the editor and reverts the value                               |
| Tab                | Edit                      | Off the first or last control, saves the value and leaves the field   |
| Enter              | Edit, inside a `textarea` | Inserts a line break                                                  |
| Ctrl / Cmd + Enter | Edit, inside a `textarea` | Saves the value; the `canSaveOnEnter` input replaces this rule        |

A click outside saves the value and closes the editor the same way `Tab` does. Leaving edit mode returns focus to the field — except on `Tab`, which hands it to the tab stop next to the field, in the direction of travel. When that tab stop belongs to another inline edit, its editor opens, so a column of fields can be filled in one pass; when there is none, the field takes focus back.

A control with an `Enter` action of its own — a button, or anything with `role="button"` — runs that action instead of saving, so one keypress does not do both. A field whose `saveHandler` request is still in flight keeps its tab stop and its focus ring: unlike a disabled one it stays reachable, it just will not reopen yet.

Content that handles clicks itself — a link, a tag — keeps its own behaviour instead of opening the editor. `interactiveSelectors` is the list that decides, `['a', 'kbq-tag']` by default; it replaces the list rather than extending it, so repeat the defaults you still want. Once the view holds such content, the field's own tab stop moves to a visually hidden control beside it, so both the content and the editor stay reachable.

### Accessibility

The view mode is announced as a `button` carrying `aria-expanded`, so assistive technology reports both that the value is editable and whether the editor is open. Its name defaults to the localized "Edit"; give the field a specific one with `aria-label` wherever the projected value alone does not say what is being edited:

```html
<kbq-inline-edit aria-label="Assignee">…</kbq-inline-edit>
```

A disabled field reports `aria-disabled` and stays out of the tab order. The icon-only save and cancel buttons of `showActions` take their names from the `a11y` locale section, alongside the `edit` name above.

A background save is not conveyed by color alone: the field announces it from a visually hidden `role="status"` region, wording it with the `saving` and `saveFailed` keys of the same locale section.

An element carrying `kbqInlineEditMenu` is stamped `role="button"` and is not named by the library, so give it an `aria-label` of its own.

### Recommendations

Inline edits should be saved immediately after a change—without requiring a global **Save** button.

**Avoid using inline editing when:**

- Inside traditional forms.
- Creating new entities (use a form instead).
- Fields require complex validation (e.g., password, email, uniqueness checks, input masks, or guided hints).
- Fields are dependent on each other (use a form when one change affects others).
- Editing critical or sensitive data.
- Saving requires additional confirmation (e.g., “Are you sure?” dialogs).

**Alternatives to inline editing:**

- A modal or popover with a form — for complex or multi-line data.
- A dedicated edit page — when more control over input is required.
- An inline form — when the field should expand into a larger editor.

## Examples

### Custom input field

By default, inline editing uses the input from `KbqFormField`.
If you need to use a different input type while retaining inline-edit functionality, apply the `getValueHandler` and `setValueHandler` properties.

[**Example: Inline edit custom handler** (`inline-edit-custom-handler`)](https://koobiq.io/examples/inline-edit-custom-handler.md)

### Clearing a field

A text field can be cleared by deleting its content and saving. In a select component, provide an explicit option such as _“Not specified”_. For other controls, consider adding a dedicated **Clear** button.

If the field cannot accept an empty value, substitute either a default value or a valid fallback.

[**Example: Inline edit on clean** (`inline-edit-on-clean`)](https://koobiq.io/examples/inline-edit-on-clean.md)

### Disabled or read-only state

When inline editing is disabled or in read-only mode, the element is displayed as static text.
If action menus are available, they remain accessible even in this state.

[**Example: Inline edit disabled** (`inline-edit-disabled`)](https://koobiq.io/examples/inline-edit-disabled.md)

### Date time input

[**Example: Inline edit date time** (`inline-edit-date-time`)](https://koobiq.io/examples/inline-edit-date-time.md)
