Documentation · Project overview
Use altEditor: true for row dialogs or an options object to customize behavior. table.altEditor() returns the existing editor or null; table.altEditor(options) creates one when absent. DataTable.altEditor exposes the constructor. The quick start shows initialization and dependencies.
Configuration precedence is: AltEditor defaults, DataTable.defaults.altEditor, root-level compatibility options, then the instance altEditor object. Explicit constructor options are applied last. Functions retain their references, arrays are copied and replaced, and unsafe object keys are rejected.
| Option | Default | Behavior |
|---|---|---|
dialog |
{ framework: 'auto', templates: { add: null, edit: null }, deleteDetails: false } |
Dialog templates, presentation, and callbacks. Configure inside altEditor. |
closeModalOnSuccess |
true |
Close a successful dialog. When false, show success and disable further submission until another dialog opens. |
encodeFiles |
true |
Read files as data URLs; false passes the first selected File object. |
debug |
false |
Log exceptions thrown by persistence callbacks after their first completion. |
inlineEdit |
disabled | Set true or configure enabled, submitOnBlur, selectText, and tabNavigation. |
The callbacks and the first three options also work at the DataTable root level. Configure translations with language.altEditor or load a JSON translation using language.altEditorUrl. Missing translation keys use English defaults. Translation files are included under translations/; see the supported languages and configuration guide.
Invalid automatic editor configuration is logged to the console and leaves DataTables usable without an editor. Explicit constructor or accessor initialization throws configuration errors to the caller.
onAddRow(editor, rowData, success, error);
onEditRow(editor, rowData, success, error, originalRowData);
onDeleteRow(editor, rowData, success, error);
onInlineEditRow(editor, rowData, success, error, originalRowData, meta);The first argument is always the AltEditor instance; editor.api() returns its DataTables API. Existing editor.s.dt access remains available for compatibility.
Dialog add/edit callbacks receive enabled form values; disabled controls are omitted. Delete receives an array of the captured rows. Inline editing receives a complete candidate row and a snapshot of the original row. Inline editing uses onEditRow if onInlineEditRow is absent. If no applicable callback is supplied, the update succeeds locally.
Set a timeout in the application transport and call error() when it expires. The editor does not impose a persistence deadline or cancel an in-flight server write. Returning a Promise or thenable settles persistence through its resolution or rejection. Resolving undefined is equivalent to success(). Normal non-thenable return values are ignored.
Call success(persistedRow) with a row object or array. Calling success() uses the submitted candidate; dialog editing preserves fields outside the form. JSON row strings are accepted. Delete ignores the response body. Call error(errorValue) to retain the form for correction and retry. Error content is rendered as text. Only the first callback, Promise, or synchronous exception settlement is accepted, and callbacks completed after destruction are ignored.
Dialog editing captures eligible fields before asynchronous collection and constructs its candidate before invoking persistence. Changing form controls or disabling them while the request is pending does not change the submitted candidate. Return success(persistedRow) explicitly for server-adjusted data.
Assign this function to onEditRow in the DataTable configuration:
function savePerson(editor, rowData, success, error, originalRowData) {
$.ajax({
url: '/people/' + encodeURIComponent(originalRowData.id),
method: 'PATCH',
contentType: 'application/json',
data: JSON.stringify(rowData),
success,
error,
});
}The target is captured when editing starts and does not change if table selection changes. Configure DataTables rowId with a unique, stable identifier when data can reload during editing or persistence. Without it, replacing row objects through Ajax or clear().rows.add() can make the original target unidentifiable, even if the new row has similar values. Such results are rejected instead of being applied to another row. Tables on the same page should use distinct row ID prefixes when their identifiers overlap.
| Method | Purpose |
|---|---|
api() |
Return the DataTables API. |
openAddDialog() |
Open an add form. |
openEditDialog(rowSelector?) |
Edit one explicit or selected row. |
openDeleteDialog(rowSelector?) |
Delete explicit or selected rows. |
refresh() |
Reload Ajax data or redraw client data without resetting paging. |
startInlineEdit(cellSelector) |
Start an eligible visible cell; return a boolean. |
commitInlineEdit() |
Validate and start persistence; return a boolean, not a persistence result. |
cancelInlineEdit() |
Cancel an unsaved cell; return a boolean. |
isInlineEditing() |
Report editing or pending cell persistence. |
reloadOptions(select, options) |
Replace options in a native or enhanced select; accepts an element or jQuery object. |
destroy() |
Release listeners, plugins, and dialog elements; also called on table destruction. |
_openAddModal, _openEditModal, and _openDeleteModal are deprecated aliases for the corresponding public methods. Dialog submissions are bound automatically.
Without an explicit row selector, edit and delete use the Select extension. Edit requires exactly one row; delete requires at least one. Without Select, pass a selector explicitly. Rejected dialog opening returns false; successful opening has no return value. Missing framework and selection messages appear beside the table when no dialog is open.
See persistence and field validation for Promise examples, structured fieldErrors, validation order, and editorValidate.
| Options | Behavior |
|---|---|
editable, visible |
Exclude a field from dialog editing or hide its dialog row. |
type |
Native input type, select, or textarea. Radio fields are excluded. The deprecated readonly type maps to a readonly text input. |
readonly, disabled, required |
Standard control attributes; disabled controls are omitted from dialog submissions. |
title, placeholder, hoverMsg |
Field label, placeholder, and input tooltip. Text is not interpreted as HTML. |
pattern, maxLength, min, max, step |
Native constraint validation where applicable to the input type. |
unique, uniqueMsg |
Validate uniqueness among loaded rows. The message uses uniqueMsg or language.error.unique. |
value |
Default add-dialog value; edit dialogs read the current row. |
options, multiple, optionsSortByLabel |
Select values, multiple selection, and label sorting. Options accept primitive arrays, value/label or id/text objects, or value-to-label maps. |
rows, cols |
Textarea dimensions. |
accept, maxFileSize |
File input type hint and optional nonnegative size limit in bytes. |
style |
Dialog control inline styles, as a string or property object. |
select2, datepicker, datetimepicker |
Optional dialog plugin configuration; meaningful native controls remain usable when plugins are absent. |
dateFormat, dateInputFormat |
Format dialog date/time values using Moment on window.moment when available; parse strictly with the input format or ISO 8601. |
editorValidate(value, context) |
Synchronous or asynchronous field validation; see custom validators. |
editorOnChange(event, editor) |
Handle a dialog field change. |
inline |
Compact dialog field layout; this is distinct from cell editing. |
special |
Deprecated compatibility data attribute; has no built-in validation behavior. |
inlineEditable, inlineEditType, inlineEditOptions, inlineEditSetValue |
Cell editing eligibility, control type, control options, and explicit row setter. |
Object rows, numeric array sources including 0, and dotted object paths are supported. Writable paths containing __proto__, prototype, or constructor are rejected, while unrelated metadata with those names is preserved when rows are copied. Complex DataTables sources, including bracket, function, and escaped-dot notation, need an explicit setter for inline editing and are excluded from dialogs. Dialogs also exclude radio fields and fields with an empty title, except hidden inputs. Use a titled select for a single choice or editable: false to explicitly exclude a column.
Uniqueness compares text and select values as strings, number fields numerically, and multiple selections by overlapping values. Empty values do not count as duplicates; use required when a value is mandatory. optionsSortByLabel uses the browser's default locale. Supply options in the desired order without this option when applications require a fixed ordering.
Dialog text and number fields retain HTML form string values; convert numeric values in the persistence callback when the data model requires numbers. Checkboxes return booleans and multiple selects return arrays of strings. Inline number controls return numbers.
Stored select values absent from the initial options are included as plain-text options so opening an editor does not discard them. Single selections preserve literal JSON strings; multiple selections also accept JSON arrays unless the string itself matches an option. reloadOptions() intentionally replaces the available choices and only retains values present in the new list, which is useful for dependent fields. Validate required choices after reloading.
Native date, time, and datetime-local controls require values such as 2026-09-11, 14:30, and 2026-09-11T14:30. Store native-compatible values and use a DataTables renderer for presentation. Dialog dateFormat also applies to time fields; custom source formats require dateInputFormat to avoid ambiguous parsing. Inline controls use raw values without Moment conversion.
maxFileSize applies before reading files with either encodeFiles setting. Omitting it preserves unrestricted file size behavior. For large files, use encodeFiles: false and upload the File separately rather than storing a data URL in table data. Applications must enforce file restrictions on the server as well.
For forms with multiple file fields, all field values and file size limits are checked before encoded file reads start. Correct an invalid file selection and submit again to retry.
For complete local HTTP persistence and raw file uploads, see Example 16. For deleting multiple selected rows, see Example 15.
With serverSide: true, the editor only has the currently loaded row snapshot. Unique validation covers loaded data, so applications must also validate on the server. Server draws remain authoritative. Use stable row IDs and reload with editor.api().ajax.reload(null, false) after persistence when necessary. A result for a row no longer available on the client is reported as an error instead of being applied elsewhere.
Use dist/dataTables.altEditor.min.js for minified JavaScript. Both builds include source maps and an MIT license banner. AMD consumers map jquery and datatables.net. CommonJS consumers can load the package after initializing their browser environment, or call its exported factory with (window, jQuery) when no global window exists. The factory returns the AltEditor constructor.
Each loaded module uses one window and jQuery context. Load a separate copy within each iframe; do not reuse one CommonJS module factory across multiple active windows.
See inline editing, events, and troubleshooting for related behavior.
The supported jQuery range is >=1.8 <4.0.0; optional frameworks and field plugins may require a narrower range. Development dependencies and examples use 3.7.1.
A compatibility check of AltEditor 4.1.1 with jQuery 4.0.0 and DataTables 2.3.8 produced a successful Rollup build, but did not pass all runtime checks. Rollup treats jQuery as an external dependency, so a successful build does not establish runtime compatibility.
- 82 of 83 unit tests passed. CommonJS loading without a global DOM window failed because jQuery 4 requires a different factory entry point in that environment.
- 13 Chromium checks covering Bootstrap 5, native dialogs, templates, and inline editing passed. These results do not establish compatibility for every optional field plugin or browser.
- Bootstrap 4.6.2 rejects jQuery 4 during initialization.
- Foundation 6.9.0 dialog focus handling calls
.sort()on a jQuery collection, which jQuery 4 no longer provides. Both Foundation browser checks failed to open a usable dialog.
See the jQuery 4 upgrade guide for the factory entry point and removed collection methods. Use jQuery 3.7.1 for the bundled examples and supported framework combinations.