diff --git a/README.md b/README.md
index 2645b79cd..c4008b844 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ This is the approach that all modern, production ready, WYSIWYG editors now take
Trix supports all evergreen, self-updating desktop and mobile browsers.
`. +## Integrating with Element Internals + +Trix will integrate `` elements with forms depending on the browser's support for [Element Internals](https://developer.mozilla.org/en-US/docs/Web/API/ElementInternals). If there is a need to disable support for `ElementInternals`, set `Trix.elements.TrixEditorElement.formAssociated = false`: + +```js +import Trix from "trix" + +Trix.elements.TrixEditorElement.formAssociated = false +``` + ## Invoking Internal Trix Actions Internal actions are defined in `controllers/editor_controller.js` and consist of: @@ -148,6 +158,126 @@ To populate a ` ` with stored content, include that content in the a Always use an associated input element to safely populate an editor. Trix won’t load any HTML content inside a ` … ` tag. +## Validating the Editor + +Out of the box, `` elements support browsers' built-in [Constraint +validation][]. When rendered with the [required][] attribute, editors will be +invalid when they're completely empty. For example, consider the following HTML: + +```html + + +``` + +Since the ` ` element is `[required]`, it is invalid when its value +is empty: + +```js +const editor = document.querySelector("trix-editor") + +editor.validity.valid // => false +editor.validity.valueMissing // => true +editor.matches(":valid") // => false +editor.matches(":invalid") // => true + +editor.value = "A value that isn't empty" + +editor.validity.valid // => true +editor.validity.valueMissing // => false +editor.matches(":valid") // => true +editor.matches(":invalid") // => false +``` + +In addition to the built-in `[required]` attribute, ` ` +elements support custom validation through their [setCustomValidity][] method. +For example, consider the following HTML: + +```js + + +``` + +Custom validation can occur at any time. For example, validation can occur after +a `trix-change` event fired after the editor's contents change: + +```js +addEventListener("trix-change", (event) => { + const editorElement = event.target + const trixDocument = editorElement.editor.getDocument() + const isValid = (trixDocument) => { + // determine the validity based on your custom criteria + return true + } + + if (isValid(trixDocument)) { + editorElement.setCustomValidity("") + } else { + editorElement.setCustomValidity("The document is not valid.") + } +} +``` + +[Constraint validation]: https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation +[required]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/required +[setCustomValidity]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity + +## Disabling the Editor + +To disable the ` `, render it with the `[disabled]` attribute: + +```html + +``` + +Disabled editors are not editable, cannot receive focus, and their values will +be ignored when their related `