From d1f0dbeca64c09f6207a8a66982feb437984fa7b Mon Sep 17 00:00:00 2001
From: Alice Pote <alice.writes.wrongs@gmail.com>
Date: Mon, 23 Oct 2023 14:10:23 -0400
Subject: [PATCH] docs(forms): add a small section with a FACE example

---
 docs/guides/forms.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/guides/forms.md b/docs/guides/forms.md
index 4f1e912da..aed5d373c 100644
--- a/docs/guides/forms.md
+++ b/docs/guides/forms.md
@@ -46,6 +46,50 @@ export class MyName {
 
 Let's go over what is happening here. First we bind the value of the input to a state variable, in this case `this.value`. We then set our state variable to the new value of the input with the `handleChange` method we have bound to `onInput`. `onInput` will fire every keystroke that the user types into the input.
 
+## Using form-associated custom elements
+
+In addition to using a `<form>` element inside of a Stencil component, as shown
+in the above example, you can also use Stencil's support for building
+form-associated custom elements to create a Stencil component that integrates
+in a native-like way with a `<form>` tag _around_ it. This allows you to build
+rich form experiences using Stencil components which leverage built-in form
+features like validation and accessibility.
+
+As an example, translating the above example to be a form-associated component
+(instead of one which includes a `<form>` element in its JSX) would look like
+this:
+
+```tsx
+@Component({
+  tag: 'my-name',
+  styleUrl: 'my-name.css',
+  formAssociated: true
+})
+export class MyName {
+  @State() value: string;
+  @AttachInternals() internals: ElementInternals;
+
+  handleChange(event) {
+    this.internals.setFormValue(event.target.value);
+  }
+
+  render() {
+    return (
+      <label>
+        Name:
+        <input
+          type="text"
+          value={this.value}
+          onInput={(event) => this.handleChange(event)}
+        />
+      </label>
+    );
+  }
+}
+```
+
+For more check out the docs for [form-association in
+Stencil](../components/form-associated.md).
 
 ## Advanced forms