The HTML aria-multiline attribute
aria-multiline="true" marks a custom text box that takes line breaks, and false, the default, marks a single-line one. That tells assistive technology what to expect, but the Enter key behaves as before until a script changes it.
Overview
The aria-multiline attribute says whether a text box accepts multiple lines of input or only a single line. It works on the textbox role, and the searchbox role inherits it. With true, the widget accepts line breaks, as a <textarea> does.
The Enter key is the difference it describes. In most browsers, Enter usually submits the form from a single-line text input and inserts a line break in a textarea. The property sets expectations about the data to enter and what that keystroke will do.
Chrome and Firefox add a line to a contenteditable box on Enter whether aria-multiline is true or false, and don't submit its form. An <input aria-multiline="true"> still submits on Enter, and a <div role="textbox"> without contenteditable takes no typing.
Leaving it out isn't neutral on an editable box. WAI-ARIA's default is false, but HTML-AAM maps editable contenteditable content to a multi-line state. Firefox exposes such a textbox with no attribute as single-line, and Chrome as multi-line, so set the value on every contenteditable textbox.
A <textarea> already maps to the textbox role with aria-multiline set to true. Use <input> or <textarea> where you can, because they have built-in semantics and keyboard support.
Syntax
<div role="textbox" contenteditable="true" aria-label="Short bio"
aria-multiline="true" style="border:1px solid"></div>
<div role="textbox" contenteditable="true" aria-label="Tag"
aria-multiline="false" style="border:1px solid"></div>Values
| Value |
|---|
| true | false |
Example
<p style="margin:0 0 6px"><label><input type="checkbox" id="multi" checked> Allow several lines</label></p>
<div id="box" role="textbox" contenteditable="true" aria-label="Message" aria-multiline="true" style="border:1px solid #767676;padding:6px;min-height:52px">Line one</div>
<p id="out" role="status" style="overflow-wrap:anywhere"></p>
<p>Press Enter in the box, then uncheck the option and press Enter again.</p>
<script>
const box = document.getElementById('box');
const multi = document.getElementById('multi');
const out = document.getElementById('out');
multi.addEventListener('change', function () {
box.setAttribute('aria-multiline', String(multi.checked));
out.textContent = 'aria-multiline is now ' + multi.checked + '.';
});
box.addEventListener('keydown', function (e) {
if (e.key !== 'Enter') return;
if (box.getAttribute('aria-multiline') === 'false') {
e.preventDefault();
out.textContent = 'The script canceled Enter, because this box is single-line.';
} else {
out.textContent = 'The script left Enter alone, so the browser added a line.';
}
});
</script>Best practices
- Cancel Enter yourself when
aria-multilineis false. Akeydownhandler withpreventDefault()stops the line break that contenteditable would add. - Call
form.requestSubmit()from that handler if Enter should send the form, because a contenteditable box doesn't do that on its own. - Read a multi-line box with
innerText. Chrome and Firefox put new lines in div elements, sotextContentruns the lines together. - Keep the attribute off comboboxes. The combobox role doesn't support it, and an editable combobox is defined as a single-line text field.
