Add docs for HTMLElement.writingSuggestions (#37036)

* Add docs for `HTMLElement.writingSuggestions` * fix desc * Update files/en-us/web/api/htmlelement/writingsuggestions/index.md * Apply suggestions from code review * Update files/en-us/web/api/htmlelement/writingsuggestions/index.md * Update files/en-us/web/api/htmlelement/writingsuggestions/index.md --------- Co-authored-by: Estelle Weyl <[email protected]>
mdn · Dec 16, 2024 · 8d5d188 · 8d5d188
1 parent d320f20
commit 8d5d188
Show file tree

Hide file tree

Showing 4 changed files with 50 additions and 3 deletions.
diff --git a/files/en-us/web/api/htmlelement/index.md b/files/en-us/web/api/htmlelement/index.md
@@ -86,6 +86,8 @@ _Also inherits properties from its parent, {{DOMxRef("Element")}}._
   - : A boolean value representing the translation.
 - {{DOMxRef("HTMLElement.virtualKeyboardPolicy")}} {{Experimental_Inline}}
   - : A string indicating the on-screen virtual keyboard behavior on devices such as tablets, mobile phones, or other devices where a hardware keyboard may not be available, if the element's content is editable (for example, it is an {{htmlelement("input")}} or {{htmlelement("textarea")}} element, or an element with the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set).
+- {{DOMxRef("HTMLElement.writingSuggestions")}}
+  - : A string indicating if browser-provided writing suggestions should be enabled under the scope of the element or not.
 
 ## Instance methods
 

diff --git a/files/en-us/web/api/htmlelement/writingsuggestions/index.md b/files/en-us/web/api/htmlelement/writingsuggestions/index.md
@@ -0,0 +1,45 @@
+---
+title: "HTMLElement: writingSuggestions property"
+short-title: writingSuggestions
+slug: Web/API/HTMLElement/writingSuggestions
+page-type: web-api-instance-property
+browser-compat: api.HTMLElement.writingSuggestions
+---
+
+{{APIRef("HTML DOM")}}
+
+The **`writingSuggestions`** property of the {{domxref("HTMLElement")}} interface is a string indicating if browser-provided writing suggestions should be enabled under the scope of the element or not.
+
+It reflects the value of the [`writingsuggestions`](/en-US/docs/Web/HTML/Global_attributes/writingsuggestions) HTML global attribute.
+
+## Value
+
+An enumerated value; possible values are:
+
+- `"true"`
+  - : The browser automatically shows the virtual keyboard when the user taps or focuses the element.
+- `"false"`
+  - : The browser does not automatically show the virtual keyboard: showing/hiding the virtual keyboard is handled manually by the script.
+
+## Examples
+
+The following example shows how to disable writing suggestions offered by user agents via script:
+
+```js
+const element = document.querySelector("input");
+
+// disable user agent writing suggestions
+element.writingSuggestions = "false";
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [`writingsuggestions`](/en-US/docs/Web/HTML/Global_attributes/writingsuggestions) HTML global attribute
diff --git a/files/en-us/web/html/global_attributes/index.md b/files/en-us/web/html/global_attributes/index.md
@@ -125,14 +125,14 @@ In addition to the basic HTML global attributes, the following global attributes
 
 - [`virtualkeyboardpolicy`](/en-US/docs/Web/HTML/Global_attributes/virtualkeyboardpolicy) {{Experimental_Inline}}
 
-  - : An [enumerated](/en-US/docs/Glossary/Enumerated) attribute used to control the on-screen virtual keyboard behavior on devices such as tablets, mobile phones, or other devices where a hardware keyboard may not be available for elements that its content is editable (for example, it is an {{htmlelement("input")}} or {{htmlelement("textarea")}} element, or an element with the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set).
+  - : An {{Glossary("enumerated")}} attribute used to control the on-screen virtual keyboard behavior on devices such as tablets, mobile phones, or other devices where a hardware keyboard may not be available for elements that its content is editable (for example, it is an {{htmlelement("input")}} or {{htmlelement("textarea")}} element, or an element with the [`contenteditable`](/en-US/docs/Web/HTML/Global_attributes/contenteditable) attribute set).
 
     - `auto` or an _empty string_, which automatically shows the virtual keyboard when the element is focused or tapped.
     - `manual`, which decouples focus and tap on the element from the virtual keyboard's state.
 
 - [`writingsuggestions`](/en-US/docs/Web/HTML/Global_attributes/writingsuggestions)
 
-  - : Used to control the behavior of the browser's writing suggestions in an input field, a section of a page, or the entire page.
+  - : An {{Glossary("enumerated")}} attribute indicating if browser-provided writing suggestions should be enabled under the scope of the element or not.
 
     - `false`, which disables the browser's writing suggestions.
     - `true` or an _empty string_, which enables writing suggestions.

diff --git a/files/en-us/web/html/global_attributes/writingsuggestions/index.md b/files/en-us/web/html/global_attributes/writingsuggestions/index.md
@@ -7,7 +7,7 @@ browser-compat: html.global_attributes.writingsuggestions
 
 {{HTMLSidebar("Global_attributes")}}
 
-The **`writingsuggestions`** [global attribute](/en-US/docs/Web/HTML/Global_attributes) is an {{glossary("enumerated")}} attribute indicating if browser-provided writing suggestions should be enabled on the element or not.
+The **`writingsuggestions`** [global attribute](/en-US/docs/Web/HTML/Global_attributes) is an {{glossary("enumerated")}} attribute indicating if browser-provided writing suggestions should be enabled under the scope of the element or not.
 
 Some browsers provide writing suggestions to users as they type in editable fields. Suggestions usually appear as greyed-out text positioned after the text cursor, completing the user's sentence. While this can be helpful to users, developers might want to turn writing suggestions off in some cases, such as when providing site-specific writing suggestions.