@iress-oss/ids-mcp-server 6.0.0-alpha.1-canary-20251204032753-fe18cab → 6.0.0-alpha.1-canary-20251204040305-3639454

package/generated/docs/components_patterns-form-docs.md

@@ -0,0 +1,2469 @@
+Form
+====
+
+Overview
+--------
+
+Use the `IressForm` component when you want to request, validate and process data from the user.
+
+[](./iframe.html?id=patterns-form--simple)
+
+```
+
+<ForwardedForm
+  actions\={<IressButton mode\="primary" type\="submit"\>Submit</IressButton\>}
+  pattern\="short"
+\>
+  <IressText element\="p"\>
+    This form is a simple example of how to use{' '}
+    <code\>
+      IressFormField    </code\>
+    {' '}with{' '}
+    <code\>
+      IressInput    </code\>
+    .  </IressText\>
+  <IressFormField
+    label\="Name"
+    name\="name"
+    render\={() \=> {}}
+    rules\={{
+      required: 'Name is required'
+    }}
+  />
+  <IressFormField
+    label\="Email address"
+    name\="email"
+    render\={() \=> {}}
+    rules\={{
+      minLength: {
+        message: 'Use a longer email address',
+        value: 6
+      },
+      required: 'Email is required'
+    }}
+  />
+</ForwardedForm\>
+
+```
+
+Props
+-----
+
+Below are the custom props you can access when using `IressForm`, which includes the props for the [`useForm` hook from React Hook Forms](https://react-hook-form.com/docs/useform). In addition to these, you have access to the original props of the underlying [`form` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form).
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| pattern | 
+
+string
+
+
+
+ | \- | short |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Key concepts
+------------
+
+As of version 5, `IressForm` is built on top of [React Hook Forms](https://react-hook-form.com/). This provides you the power of React Hook Forms with the convenience of IDS form components. However, there are some key differences to be aware of as it may affect how you build your forms.
+
+### State management
+
+`IressForm` manages the state of the form, including the form data and validation. This is done using the `useForm` hook from React Hook Forms. This hook provides a way to manage the form state, and provides methods to interact with the form. This was done to simplify the form components, make them more predictable (as the form becomes the single source of truth for all form related data) and improve performance by reducing re-renders (very important for large forms).
+
+Due to this change, there are a few things you should consider during development:
+
+*   Avoid using the `useState` hook to manage form state. Instead, use the `IressForm.useForm` hook or the `ref` of the `IressForm` component to interact with the form state. The initial value of the form can be set using the `defaultValues` prop, but from then on you should be using either the hook or ref to interact with the form state.
+*   Avoid using `onChange` handlers on form fields to react to form values. Instead, use the `IressForm.useWatch` hook to watch the value of a field and conditionally render fields based on the value of another field.
+
+See below an example comparing a version 4 and version 5 `IressForm` when managing form state.
+
+[](./iframe.html?id=patterns-form--state-management-v-4-to-v-5)
+
+Diff
+
+Old
+
+New
+
+<table class="css-1n5o7vh-diff-container"><tbody><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">import { IressForm, IressField, IressInput, IressCheckboxGroup, IressCheckbox } from '@iress/components';</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">import { IressForm, IressFormField, IressInput, IressCheckboxGroup, IressCheckbox } from '@iress-oss/ids-components';</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-10regm7-empty-line"><pre></pre></td><td class="css-vl0irh-content css-10regm7-empty-line"><pre class="css-o1u8iu-content-text"></pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-10regm7-empty-line"><pre></pre></td><td class="css-vl0irh-content css-10regm7-empty-line"><pre class="css-o1u8iu-content-text"></pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">export const App = () =&gt; {</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">const ConditionalFields = () =&gt; {</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">  // We need to create our own state to manage the visibility of the fields, </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">  // Instead of creating our own state, we can now use the form state via the useWatch hook, </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">  // which means we have two sources of truth potentially making our code harder to maintain</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">  // meaning we still have a single source of truth</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">  const [show, setShow] = useState(['name']);</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">  const show = IressForm.useWatch({ name: 'show'});</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-10regm7-empty-line"><pre></pre></td><td class="css-vl0irh-content css-10regm7-empty-line"><pre class="css-o1u8iu-content-text"></pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">  return (</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">      &lt;IressForm&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">    &lt;&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">        &lt;IressField label="Show fields"&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      &lt;IressFormField </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">          &lt;IressCheckboxGroup value={show} onChange={(newValues) =&gt; setShow(newValues)}&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">        label="Show fields" </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">        name="show"</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">        render={(controlledProps) =&gt; (</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">          &lt;IressCheckboxGroup {...controlledProps}&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">            &lt;IressCheckbox value="name"&gt;Name&lt;/IressCheckbox&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">            &lt;IressCheckbox value="email"&gt;Email&lt;/IressCheckbox&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">          &lt;/IressCheckboxGroup&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">        &lt;/IressField&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">        )}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">        {show.includes('name') &amp;&amp; (</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      /&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">          &lt;IressField label="Name"&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      {show?.includes('name') &amp;&amp; (</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">            &lt;IressInput name="name" /&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">        &lt;IressFormField </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">          &lt;/IressField&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">          label="Name" </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">        )}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">          name="name"</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">        {show.includes('email') &amp;&amp; (</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">          render={(controlledProps) =&gt; &lt;IressInput {...controlledProps} /&gt;}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">          &lt;IressField label="Email"&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">        /&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">            &lt;IressInput name="email" type="email" /&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      )}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">          &lt;/IressField&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      {show?.includes('email') &amp;&amp; (</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">        )}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">        &lt;IressFormField </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">      &lt;/IressForm&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">          label="Email" </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">          name="email"</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">          render={(controlledProps) =&gt; &lt;IressInput {...controlledProps} type="email" /&gt;}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">        /&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      )}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">     &lt;/&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">  );</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">};</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-10regm7-empty-line css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-10regm7-empty-line css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text"></pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">export const App = () =&gt; (</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">  &lt;IressForm defaultValues={{ show: ['name'] }}&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">    &lt;ConditionalFields /&gt; </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">  &lt;/IressForm&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">);</pre></td></tr></tbody></table>
+
+```
+
+{
+  render: () \=> <DiffViewer allowModeChange oldValue\={\`import { IressForm, IressField, IressInput, IressCheckboxGroup, IressCheckbox } from '@iress/components';
+export const App = () => {
+  // We need to create our own state to manage the visibility of the fields,  // which means we have two sources of truth potentially making our code harder to maintain  const \[show, setShow\] = useState(\['name'\]);
+  return (      <IressForm>        <IressField label="Show fields">          <IressCheckboxGroup value={show} onChange={(newValues) => setShow(newValues)}>            <IressCheckbox value="name">Name</IressCheckbox>            <IressCheckbox value="email">Email</IressCheckbox>          </IressCheckboxGroup>        </IressField>        {show.includes('name') && (          <IressField label="Name">            <IressInput name="name" />          </IressField>        )}        {show.includes('email') && (          <IressField label="Email">            <IressInput name="email" type="email" />          </IressField>        )}      </IressForm>  );
+};\`} newValue\={\`import { IressForm, IressFormField, IressInput, IressCheckboxGroup, IressCheckbox } from '@iress-oss/ids-components';
+const ConditionalFields = () => {
+  // Instead of creating our own state, we can now use the form state via the useWatch hook,  // meaning we still have a single source of truth  const show = IressForm.useWatch({ name: 'show'});
+  return (    <>      <IressFormField        label="Show fields"        name="show"        render={(controlledProps) => (          <IressCheckboxGroup {...controlledProps}>            <IressCheckbox value="name">Name</IressCheckbox>            <IressCheckbox value="email">Email</IressCheckbox>          </IressCheckboxGroup>        )}      />      {show?.includes('name') && (        <IressFormField          label="Name"          name="name"          render={(controlledProps) => <IressInput {...controlledProps} />}        />      )}      {show?.includes('email') && (        <IressFormField          label="Email"          name="email"          render={(controlledProps) => <IressInput {...controlledProps} type="email" />}        />      )}     </>  );
+};
+export const App = () => (
+  <IressForm defaultValues={{ show: \['name'\] }}>    <ConditionalFields />  </IressForm>
+);\`} /\>
+}
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+### Validation
+
+Validation is now done declaratively using the `rules` prop on the `IressFormField` component. This is based on the [rules available in React Hook Forms](https://www.react-hook-form.com/api/useform/register/#options). This change was made to allow for more complex validation rules to be implemented.
+
+Due to this change, there are a few things you should consider during development:
+
+*   If you want validation messages to be shown on form controls, you need to use the `IressFormField` component to wrap around the form control and set the `rules` prop. This will allow the form to manage the validation state of the field.
+*   Although you can still use props such as `maxLength` on `IressInput`, these no longer propagate to the form validation. You need to use the `rules` prop to set these validation rules as well, and rely on `maxLength` for the input to stop the user from entering more characters than allowed (a user experience improvement that we definitely recommend).
+*   You can no longer override default error messages for the whole form. To override the default messages, you must specify them in the `rules` prop per `IressFormField`.
+
+See below an example comparing a version 4 and version 5 `IressForm` when adding validation rules.
+
+[](./iframe.html?id=patterns-form--validation-v-4-to-v-5)
+
+Diff
+
+Old
+
+New
+
+<table class="css-1n5o7vh-diff-container"><tbody><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">import { IressForm, IressField, IressInput, IressButton } from '@iress/components';</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">import { IressForm, IressFormField, IressInput, IressButton } from '@iress-oss/ids-components';</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-10regm7-empty-line"><pre></pre></td><td class="css-vl0irh-content css-10regm7-empty-line"><pre class="css-o1u8iu-content-text"></pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">export const App = () =&gt; (</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">  &lt;IressForm valueMissing="{{fieldName}} needs to be filled in!"&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">  &lt;IressForm&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">    &lt;IressField label="Name"&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">    &lt;IressFormField </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">      &lt;IressInput name="name" required /&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      label="Name"</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">    &lt;/IressField&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      name="name"</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">    &lt;IressField label="Email"&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      render={(controlledProps) =&gt; &lt;IressInput {...controlledProps} /&gt;}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">      &lt;IressInput name="email" maxLength={10} /&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      rules={{ required: 'Name needs to be filled in!' }}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-rq9a2a-diff-removed"><pre>-</pre></td><td class="css-vl0irh-content css-rq9a2a-diff-removed"><pre class="css-o1u8iu-content-text">    &lt;/IressField&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">    /&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">    &lt;IressFormField </pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      label="Email"</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      name="email"</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      render={(controlledProps) =&gt; &lt;IressInput {...controlledProps} type="email" maxLength={10} /&gt;}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">      rules={{ maxLength: 10 }}</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker css-cnnxkz-diff-added"><pre>+</pre></td><td class="css-vl0irh-content css-cnnxkz-diff-added"><pre class="css-o1u8iu-content-text">    /&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">    &lt;IressButton type="submit" mode="primary"&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">      Sign up</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">    &lt;/IressButton&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">  &lt;/IressForm&gt;</pre></td></tr><tr class="css-1n7ec1i-line"><td class="css-17vezug-marker"><pre></pre></td><td class="css-vl0irh-content"><pre class="css-o1u8iu-content-text">);</pre></td></tr></tbody></table>
+
+```
+
+{
+  render: () \=> <DiffViewer allowModeChange oldValue\={\`import { IressForm, IressField, IressInput, IressButton } from '@iress/components';
+export const App = () => (
+  <IressForm valueMissing="{{fieldName}} needs to be filled in!">    <IressField label="Name">      <IressInput name="name" required />    </IressField>    <IressField label="Email">      <IressInput name="email" maxLength={10} />    </IressField>    <IressButton type="submit" mode="primary">      Sign up    </IressButton>  </IressForm>
+);\`} newValue\={\`import { IressForm, IressFormField, IressInput, IressButton } from '@iress-oss/ids-components';
+export const App = () => (
+  <IressForm>    <IressFormField      label="Name"      name="name"      render={(controlledProps) => <IressInput {...controlledProps} />}      rules={{ required: 'Name needs to be filled in!' }}    />    <IressFormField      label="Email"      name="email"      render={(controlledProps) => <IressInput {...controlledProps} type="email" maxLength={10} />}      rules={{ maxLength: 10 }}    />    <IressButton type="submit" mode="primary">      Sign up    </IressButton>  </IressForm>
+);\`} />
+}
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+### Syncing state
+
+For most scenarios, you should use the `onSubmit` event to sync the form data with other state management systems (eg. server, browser storage or state management libraries such as Redux). This event is emitted when the form passes validation, and contains a map of the field names and the data entered by the user.
+
+For more complex scenarios, you may need to sync a field value before the form is submitted. In this case, you can use the `IressForm.useWatch` hook to watch the value of a field and sync it with your state.
+
+Consider the following for your development:
+
+*   Only use other state management systems to fill out the form at the initial render using `defaultValues`. After that, use the `onSubmit` event to sync the form data with your state.
+*   If you need to set form with data coming from an external system, use the `ref` of the form to `reset` the form values.
+
+const ref \= useRef<FormRef | null\>(null);
+const api \= useApi();
+const handleSubmit \= async (data) \=> {
+  // Sync the form data with your state
+  const details \= await api.updateUser(data);
+  // Update the form with the new data
+  ref.current?.reset(details);
+};
+return (
+  <IressForm onSubmit\={handleSubmit} ref\={ref}\>
+    ...  </IressForm\>
+);
+
+```
+
+Usage
+-----
+
+### Patterns
+
+The `IressForm` component supports different patterns to ensure consistency in how forms are displayed depending on the context of the form.
+
+1.  `long`: This pattern is used when a form has more than 8 fields. It has the following characteristics:
+    *   The `heading` and `actions` are displayed at the top of the form and can be `sticky`, ensuring they are always visible to the user.
+    *   The validation errors are displayed when the user blurs out of a field (ie. moves to the next field), ensuring that the user is informed of any errors before submitting the form.
+2.  `short`: This is the default pattern and should be used when a form has 8 or fewer fields, usually for familiar data such as the user's login details. It has the following characteristics:
+    *   The `heading` is displayed at the top of the for and the `actions` are displayed at the bottom of the form.
+    *   The validation errors are displayed when the user submits the form to ensure that the user is not overwhelmed with errors when filling out the form.
+
+**Note:** It is recommended to use the patterns above for new applications, or those doing an overhaul, as they provide a consistent user experience across forms. For older products, please follow the existing patterns in your application to ensure consistency with the rest of the product.
+
+### Fields
+
+Use the `IressFormField` component to create form fields. This component is a layout component that wraps around form controls such as `IressInput`. It provides a consistent layout for form fields, and hooks into the `IressForm` component to provide validation and error handling.
+
+It has three required props:
+
+*   `name`: The name of the field, which will be used to identify the field in the form data.
+*   `label`: The label for the field.
+*   `render`: A render prop that renders the form control. It is passed an object containing the props to be spread onto the form control to allow it to be controlled by the form.
+
+<IressFormField
+  name\="email"
+  label\="Email"
+  render\={(controlledProps) \=> <IressInput {...controlledProps} type\="email" />}
+/>
+
+```
+
+#### Supported form controls
+
+Here are some examples of how to use `IressFormField` with different form controls. If you are using a form control that has multiple inputs inside (for example, `IressCheckboxGroup`), you can use `IressFormFieldset`, which changes the HTML structure to use a `fieldset` and `legend` element to group the inputs.
+
+[](./iframe.html?id=patterns-form--fields)
+
+```
+
+<ForwardedForm
+  actions\={<IressButton mode\="primary" type\="submit"\>Submit</IressButton\>}
+  heading\="All supported form fields"
+  pattern\="long"
+\>
+  <IressText element\="p"\>
+    This form showcases all the different components you can use within{' '}
+    <code\>
+      IressFormField    </code\>
+    .  </IressText\>
+  <IressFormField
+    label\="Name"
+    name\="name"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="Date"
+    name\="date"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="Gender"
+    name\="gender"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="Gender with icons"
+    name\="gender-with-icons"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormFieldset
+    label\="Hobbies"
+    name\="hobbies"
+    render\={() \=> {}}
+    rules\={{
+      required: 'Select at least one hobby'
+    }}
+  />
+  <IressFormFieldset
+    label\="Food of preference"
+    name\="food"
+    render\={() \=> {}}
+    rules\={{
+      required: 'Select at least one food of preference'
+    }}
+  />
+  <IressFormField
+    label\="Terms and privacy policy"
+    name\="terms"
+    render\={() \=> {}}
+    rules\={{
+      required: 'You need to agree to the terms and conditions before proceeding'
+    }}
+  />
+  <IressFormField
+    hint\="Type to copy an existing character's name"
+    label\="Your star wars name"
+    name\="star\_wars\_name"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="What's your pain level?"
+    name\="pain\_level"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="Favourite email domains"
+    name\="email\_domains"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+</ForwardedForm\>
+
+```
+
+#### IressFormField props
+
+| Name | Description | Default |
+| --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- |
+| alert | 
+
+\-
+
+ | \- |
+| children | 
+
+array
+
+
+
+ | \- |
+| heading | 
+
+string
+
+
+
+ | \- |
+| pattern | 
+
+string
+
+
+
+ | \- |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+### Rules
+
+Use the `rules` prop on the `IressFormField` component to add validation rules. These are based on the [rules available in React Hook Forms](https://www.react-hook-form.com/api/useform/register/#options). The following rules are supported.
+
+**Note:** In version 5, you can no longer override default error messages for the whole form. To override the default messages, you must specify them in the `rules` prop per `IressFormField`.
+
+#### `required`
+
+A boolean which, if `true`, indicates that the input must have a value before the form can be submitted. You can assign a string to return a custom error message.
+
+[](./iframe.html?id=patterns-form-rules--required)
+
+```
+
+<ForwardedForm\>
+  <IressFormField
+    hint\=""
+    label\="Default message"
+    name\="IressInput-default"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    hint\=""
+    label\="Custom message"
+    name\="IressInput-custom"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      required: 'Please check this field'
+    }}
+  />
+  <IressButton
+    mode\="primary"
+    type\="submit"
+  \>
+    Validate  </IressButton\>
+</ForwardedForm\>
+
+```
+
+#### Adjust
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+#### `maxLength`
+
+The maximum character length of the value to accept for this input.
+
+**Notes**
+
+*   For `IressInput`, you should also set the `maxLength` to stop the user from entering more characters than allowed.
+*   Only applies to: `IressAutocomplete`, `IressInput`, `IressRadioGroup` and `IressSelect`.
+
+[](./iframe.html?id=patterns-form-rules--max-length)
+
+```
+
+<ForwardedForm\>
+  <IressFormField
+    hint\="Enter a maximum length of 5 characters"
+    label\="Default message"
+    name\="IressInput-default"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      maxLength: 5
+    }}
+  />
+  <IressFormField
+    hint\="Enter a maximum length of 5 characters"
+    label\="Custom message"
+    name\="IressInput-custom"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      maxLength: {
+        message: 'Please enter a max length of 5 characters!',
+        value: 5
+      }
+    }}
+  />
+  <IressButton
+    mode\="primary"
+    type\="submit"
+  \>
+    Validate  </IressButton\>
+</ForwardedForm\>
+
+```
+
+#### Adjust
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+#### `minLength`
+
+The minimum character length of the value to accept for this input.
+
+**Notes**
+
+*   For `IressInput`, you should also set the `minLength` to stop the user from entering more characters than allowed.
+*   Only applies to: `IressAutocomplete`, `IressInput`, `IressRadioGroup` and `IressSelect`.
+
+[](./iframe.html?id=patterns-form-rules--min-length)
+
+```
+
+<ForwardedForm\>
+  <IressFormField
+    hint\="Enter a minimum length of 7 characters"
+    label\="Default message"
+    name\="IressInput-default"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      minLength: 7
+    }}
+  />
+  <IressFormField
+    hint\="Enter a minimum length of 7 characters"
+    label\="Custom message"
+    name\="IressInput-custom"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      minLength: {
+        message: 'Please enter a min length of 7 characters!',
+        value: 7
+      }
+    }}
+  />
+  <IressButton
+    mode\="primary"
+    type\="submit"
+  \>
+    Validate  </IressButton\>
+</ForwardedForm\>
+
+```
+
+#### Adjust
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+#### `max`
+
+The maximum number to accept for this input.
+
+**Notes**
+
+*   Only applies to: `IressAutocomplete`, `IressInput`, `IressRadioGroup` and `IressSelect`.
+
+[](./iframe.html?id=patterns-form-rules--max)
+
+```
+
+<ForwardedForm\>
+  <IressFormField
+    hint\="Select a maximum of 2"
+    label\="Default message"
+    name\="IressInput-default"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      max: 2
+    }}
+  />
+  <IressFormField
+    hint\="Select a maximum of 2"
+    label\="Custom message"
+    name\="IressInput-custom"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      max: {
+        message: 'Please enter a max of 2!',
+        value: 2
+      }
+    }}
+  />
+  <IressButton
+    mode\="primary"
+    type\="submit"
+  \>
+    Validate  </IressButton\>
+</ForwardedForm\>
+
+```
+
+#### Adjust
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+#### `min`
+
+The minimum number to accept for this input.
+
+**Notes**
+
+*   Only applies to: `IressAutocomplete`, `IressInput`, `IressRadioGroup` and `IressSelect`.
+
+[](./iframe.html?id=patterns-form-rules--min)
+
+```
+
+<ForwardedForm\>
+  <IressFormField
+    hint\="Select a minimum of 20"
+    label\="Default message"
+    name\="IressInput-default"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      min: 20
+    }}
+  />
+  <IressFormField
+    hint\="Select a minimum of 20"
+    label\="Custom message"
+    name\="IressInput-custom"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      min: {
+        message: 'Please enter a min of 20!',
+        value: 20
+      }
+    }}
+  />
+  <IressButton
+    mode\="primary"
+    type\="submit"
+  \>
+    Validate  </IressButton\>
+</ForwardedForm\>
+
+```
+
+#### Adjust
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+#### `pattern`
+
+The accepted regex pattern for the input.
+
+**Notes**
+
+*   Only applies to: `IressAutocomplete`, `IressInput`, `IressRadioGroup` and `IressSelect`.
+
+[](./iframe.html?id=patterns-form-rules--pattern)
+
+```
+
+<ForwardedForm\>
+  <IressFormField
+    hint\="Enter a valid email address"
+    label\="Default message"
+    name\="IressInput-default"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      pattern: /^\[a-zA-Z0-9.!#$%&'\*+/=?^\_\`{|}~-\]+@\[a-zA-Z0-9\](?:\[a-zA-Z0-9-\]{0,61}\[a-zA-Z0-9\])?(?:\\.\[a-zA-Z0-9\](?:\[a-zA-Z0-9-\]{0,61}\[a-zA-Z0-9\])?)\*$/
+    }}
+  />
+  <IressFormField    hint="Enter a valid email address"    label="Custom message"    name="IressInput-custom"    render={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules={{
+      pattern: {
+        message: 'Please enter a valid email address!',
+        value: /^\[a-zA-Z0-9.!#$%&'\*+/=?^\_\`{|}~-\]+@\[a-zA-Z0-9\](?:\[a-zA-Z0-9-\]{0,61}\[a-zA-Z0-9\])?(?:\\.\[a-zA-Z0-9\](?:\[a-zA-Z0-9-\]{0,61}\[a-zA-Z0-9\])?)\*$/
+      }
+    }}
+  />  <IressButton
+    mode\="primary"
+    type\="submit"
+  \>
+    Validate  </IressButton\>
+</ForwardedForm\>
+
+```
+
+#### Adjust
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+#### `minDate`
+
+The minimum date to accept for this input.
+
+**Note:** This is a custom rule created for `IressForm` and its sub-components. It will translate the rule into a `validate` rule for react-hook-forms. It will not work with a `validate` function, only if you set the `validate` prop to an `object` of functions.
+
+[](./iframe.html?id=patterns-form-rules--min-date)
+
+```
+
+{
+  ...Default,
+  args: {
+    element: 'IressInputDate',
+    field: {
+      hint: 'Enter a date after today'
+    },
+    rules: {
+      minDate: new Date()
+    },
+    customRules: {
+      minDate: {
+        value: new Date(),
+        message: 'Please enter a date after today!'
+      }
+    }
+  }
+}
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+\-
+
+ | \- | \- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+#### `maxDate`
+
+The maximum date to accept for this input.
+
+**Note:** This is a custom rule created for `IressForm` and its sub-components. It will translate the rule into a `validate` rule for react-hook-forms. It will not work with a `validate` function, only if you set the `validate` prop to an `object` of functions.
+
+[](./iframe.html?id=patterns-form-rules--max-date)
+
+```
+
+{
+  ...Default,
+  args: {
+    element: 'IressInputDate',
+    field: {
+      hint: 'Enter a date before today'
+    },
+    rules: {
+      maxDate: new Date()
+    },
+    customRules: {
+      maxDate: {
+        value: new Date(),
+        message: 'Please enter a date before today!'
+      }
+    }
+  }
+}
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+\-
+
+ | \- | \- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+#### `email`
+
+Ensures the input is a valid email address.
+
+**Note:** This is a custom rule created for `IressForm` and its sub-components. It will translate the rule into a `validate` rule for react-hook-forms. It will not work with a `validate` function, only if you set the `validate` prop to an `object` of functions.
+
+[](./iframe.html?id=patterns-form-rules--email)
+
+```
+
+<ForwardedForm\>
+  <IressFormField
+    hint\="Enter an email address"
+    label\="Default message"
+    name\="IressInput-default"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      email: true
+    }}
+  />
+  <IressFormField
+    hint\="Enter an email address"
+    label\="Custom message"
+    name\="IressInput-custom"
+    render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+    rules\={{
+      email: 'Please enter a valid email address!'
+    }}
+  />
+  <IressButton
+    mode\="primary"
+    type\="submit"
+  \>
+    Validate  </IressButton\>
+</ForwardedForm\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+\-
+
+ | \- | \- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+#### `validate`
+
+You can pass a callback function as the argument to validate, or you can pass an object of callback functions to validate against all of them. This function will be executed on its own without depending on other validation rules included.
+
+**Notes**
+
+*   for `object` or `array` input data, it's recommended to use the validate function for validation as the other rules mostly apply to `string`, `string[]`, `number` and `boolean` data types.
+
+[](./iframe.html?id=patterns-form-rules--validate)
+
+```
+
+<ForwardedForm\>
+  <IressFormFieldset
+    hint\="If checkbox, click two items to pass. Anything else, make sure it is Google."
+    label\="Default message"
+    name\="IressCheckboxGroup-default"
+    render\={(controlledProps) \=> (
+      <IressCheckboxGroup {...controlledProps}\>
+        <IressCheckbox value\="reading"\>Reading</IressCheckbox\>
+        <IressCheckbox value\="writing"\>Writing</IressCheckbox\>
+      </IressCheckboxGroup\>
+    )}
+    rules\={{
+      validate: {
+        atLeastTwoItems: (value) \=> Array.isArray(value) ? value.length \>= 2 : true,
+        isGoogle: (value) \=> Array.isArray(value) ? true : value \=== "Google"
+      }
+    }}
+  />
+  <IressFormFieldset
+    hint\="If checkbox, click two items to pass. Anything else, make sure it is Google."
+    label\="Custom message"
+    name\="IressCheckboxGroup-custom"
+    render\={(controlledProps) \=> (
+      <IressCheckboxGroup {...controlledProps}\>
+        <IressCheckbox value\="reading"\>Reading</IressCheckbox\>
+        <IressCheckbox value\="writing"\>Writing</IressCheckbox\>
+      </IressCheckboxGroup\>
+    )}
+    rules\={{
+      validate: {
+        atLeastTwoItems: (value) \=> (Array.isArray(value) ? value.length \>= 2 : true) || "Please select at least two items!",
+        isGoogle: (value) \=> (Array.isArray(value) ? true : value \=== "Google") || "I guess you are not evil!"
+      }
+    }}
+  />
+  <IressButton
+    mode\="primary"
+    type\="submit"
+  \>
+    Validate  </IressButton\>
+</ForwardedForm\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| children | 
+\-
+
+ | \- | \- |
+| Show Storybook only itemsStorybook only | Show Storybook only items |
+
+### Handling submission
+
+When the form passes validation (if not disabled), the `onSubmit` event is emitted. Its event details contain a map of the field names and the data entered by the user.
+
+[](./iframe.html?id=patterns-form--handling-submission)
+
+```
+
+import {
+  IressTable,
+  type IressFormProps,
+  IressForm,
+  IressModal,
+  IressFormField,
+  IressInput,
+  IressButton,
+} from '@iress-oss/ids-components';
+import { useState } from 'react';
+interface FieldValues {
+  name?: string;
+  email?: string;
+}
+export const FormSubmission \= () \=> {
+  const \[showModal, setShowModal\] \= useState(false);
+  const \[submitted, setSubmitted\] \= useState<FieldValues | undefined\>(
+    undefined,
+  );
+  return (
+    <IressForm
+      {...{
+  pattern: 'short',
+}}
+      onSubmit\={(data) \=> {
+        setSubmitted(data);
+        setShowModal(true);
+      }}
+    \>
+      <IressFormField
+        label\="Name"
+        name\="name"
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{
+          required: 'Name is required',
+        }}
+      />
+      <IressFormField
+        label\="Email address"
+        name\="email"
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{
+          minLength: {
+            message: 'Use a longer email address',
+            value: 6,
+          },
+          required: 'Email is required',
+        }}
+      />
+      <IressButton mode\="primary" type\="submit"\>
+        Sign up      </IressButton\>
+      <IressModal
+        show\={showModal}
+        onShowChange\={setShowModal}
+        onExited\={() \=> setSubmitted(undefined)}
+      \>
+        <IressTable
+          caption\="Submitted details"
+          rows\={Object.entries(submitted ?? {}).map((entry) \=> ({
+            name: entry\[0\],
+            value: JSON.stringify(entry\[1\], null, 2),
+          }))}
+        />
+      </IressModal\>
+    </IressForm\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | \- |
+| onSubmit | 
+
+\-
+
+ | \- | \- |
+| pattern | 
+
+string
+
+
+
+ | \- | short |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Behaviour
+---------
+
+*   Initial form validation is done when the user first submits the form. This allows them to focus on entering data without being overwhelmed by validation errors.
+*   If there are validation errors on submission, they will be shown at the form level as a summary, as well as per field. Only the first failing error will be displayed per field.
+*   After the first submission, fields are validated on change, to provide users instant feedback as they are now at the validation phase.
+
+**Note:** The default user experience regarding validation is different to previous versions of IDS. This change was done to align IDS with the typical user experience found in other applications. If you would like to change the behaviour to be more consistent with the original IDS, set the `mode` prop of the form to `onBlur`.
+
+Examples
+--------
+
+### Pre-fill the form
+
+You can set the `defaultValues` prop to pre-fill the form values.
+
+[](./iframe.html?id=patterns-form--default-values)
+
+```
+
+<ForwardedForm
+  actions\={<IressButton mode\="primary" type\="submit"\>Submit</IressButton\>}
+  defaultValues\={{
+    email: 'luke.skywalker@iress.com',
+    name: 'Luke Skywalker'
+  }}
+  pattern\="short"
+\>
+  <IressText element\="p"\>
+    This form is a simple example of how to use{' '}
+    <code\>
+      IressFormField    </code\>
+    {' '}with{' '}
+    <code\>
+      IressInput    </code\>
+    .  </IressText\>
+  <IressFormField
+    label\="Name"
+    name\="name"
+    render\={() \=> {}}
+    rules\={{
+      required: 'Name is required'
+    }}
+  />
+  <IressFormField
+    label\="Email address"
+    name\="email"
+    render\={() \=> {}}
+    rules\={{
+      minLength: {
+        message: 'Use a longer email address',
+        value: 6
+      },
+      required: 'Email is required'
+    }}
+  />
+</ForwardedForm\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| pattern | 
+
+string
+
+
+
+ | \- | short |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+### Custom error handling
+
+The `onError` prop allows you to listen to any field errors. It takes two arguments. The first is a map of the field name and an object containing the first error message and type. The second is a ref to the original element that caused the error (the ref of the underlying input).
+
+One use case for this prop is to create your own visible error summary at the top of the form, or to log errors to an external service.
+
+[](./iframe.html?id=patterns-form--custom-error-handling)
+
+```
+
+import {
+  IressTable,
+  type IressFormProps,
+  IressForm,
+  IressModal,
+  IressStack,
+  IressFormField,
+  IressInput,
+  IressButton,
+  IressText,
+} from '@iress-oss/ids-components';
+import { useState } from 'react';
+import { type FieldErrors } from 'react-hook-form';
+interface FieldValues {
+  name?: string;
+  email?: string;
+}
+export const CustomErrorHandlingForm \= () \=> {
+  const \[errors, setErrors\] \= useState<FieldErrors<FieldValues\> | undefined\>(
+    undefined,
+  );
+  return (
+    <IressForm {...{
+  pattern: 'short',
+}} onError\={(data) \=> setErrors(data)}\>
+      <IressText mb\="md"\>
+        <h2\>Custom error handling</h2\>
+        <p\>
+          Demonstrates usage of the <code\>onError</code\> prop to show a modal          when there are issues with the form.        </p\>
+      </IressText\>
+      <IressFormField
+        label\="Name"
+        name\="name"
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{
+          required: 'Name is required',
+        }}
+      />
+      <IressFormField
+        label\="Email address"
+        name\="email"
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{
+          minLength: {
+            message: 'Use a longer email address',
+            value: 6,
+          },
+          required: 'Email is required',
+        }}
+      />
+      <IressButton mode\="primary" type\="submit"\>
+        Sign up      </IressButton\>
+      <IressModal
+        show\={!!errors}
+        onShowChange\={(show) \=> !show && setErrors(undefined)}
+      \>
+        <IressTable
+          caption\="Errors"
+          rows\={Object.entries(errors ?? {}).map((\[name, errorDetails\]) \=> ({
+            name,
+            errorDetails: (
+              <IressStack gap\="sm"\>
+                <ul\>
+                  <li\>Error type: {String(errorDetails?.type)}</li\>
+                  <li\>Error message: {String(errorDetails?.message)}</li\>
+                </ul\>
+              </IressStack\>
+            ),
+          }))}
+        />
+      </IressModal\>
+    </IressForm\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | \- |
+| onError | 
+
+\-
+
+ | \- | \- |
+| onSubmit | 
+
+\-
+
+ | \- | \- |
+| pattern | 
+
+string
+
+
+
+ | \- | short |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+### `values`
+
+If you would like more control over each value of the form, you should use the `values` prop. This will make the form controlled, meaning it will rely completely on the `values` state to render the value of each field. You will need to use the `onSubmit` prop to sync the form value with your state.
+
+Use cases where you may need the `values` prop:
+
+*   Syncing with a server once the values have been processed
+*   Syncing the value with browser storage
+
+**Note:** `values` takes precedence over `defaultValues`. To ensure your form state is predictable, it is best to only use one prop to manage form values.
+
+[](./iframe.html?id=patterns-form--values)
+
+```
+
+interface FieldValues {
+  name?: string;
+  email?: string;
+}
+export const ControlledForm \= (args: IressFormProps<FieldValues\>) \=> {
+  const \[values, setValues\] \= useState<FieldValues\>({
+    name: 'Leia Skywalker',
+    email: 'leia.skywalker@iress.com',
+  });
+  const \[preview, setPreview\] \= useState(false);
+  return (
+    <\>
+      <IressForm
+        {...args}
+        onSubmit\={(data) \=> {
+          setValues(data);
+          setPreview(true);
+        }}
+        values\={values}
+        mode\="onChange"
+      \>
+        <IressFormField
+          label\="Name"
+          name\="name"
+          render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+          rules\={{
+            required: 'Name is required',
+          }}
+        />
+        <IressFormField
+          label\="Email address"
+          name\="email"
+          render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+          rules\={{
+            minLength: {
+              message: 'Use a longer email address',
+              value: 6,
+            },
+            required: 'Email is required',
+          }}
+        />
+      </IressForm\>
+      <IressDivider my\="md" />
+      <IressInline gap\="sm"\>
+        <IressButton onClick\={() \=> setPreview(true)}\>Last update</IressButton\>
+        <IressButton
+          onClick\={() \=>
+            setValues({
+              name: '',
+              email: '',
+            })
+          }
+        \>
+          Clear        </IressButton\>
+      </IressInline\>
+      <IressModal show\={!!preview} onShowChange\={(show) \=> setPreview(show)}\>
+        <IressTable
+          caption\="Last update"
+          rows\={Object.entries(values).map((entry) \=> ({
+            name: entry\[0\],
+            value: JSON.stringify(entry\[1\], null, 2),
+          }))}
+        />
+      </IressModal\>
+    </\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| onSubmit | 
+
+\-
+
+ | \- | \- |
+| pattern | 
+
+string
+
+
+
+ | \- | short |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+### Disable validation
+
+Disabling validation is not possible with the `IressForm` component. In cases where you do need to disable validation, please consider the following:
+
+1.  Use a non-submitting button to save a draft (eg. `<IressButton type="button">Save as draft</IressButton>`). Then you can use the `ref` of the form to get the form data.
+2.  Use a native `form` element, and customise the error handling.
+
+Here we have an example showcasing option one.
+
+[](./iframe.html?id=patterns-form--disable-validation)
+
+```
+
+import {
+  type FormRef,
+  IressButton,
+  IressDivider,
+  IressForm,
+  IressFormField,
+  type IressFormProps,
+  IressInput,
+  IressToasterProvider,
+  useToaster,
+} from '@iress-oss/ids-components';
+import { useRef } from 'react';
+interface FieldValues {
+  name?: string;
+  email?: string;
+}
+const Form \= () \=> {
+  const { success, error } \= useToaster();
+  const formRef \= useRef<FormRef<FieldValues\>>(null);
+  return (
+    <\>
+      <IressForm        {...{
+  actions: {
+    type: {
+      \_\_docgenInfo: {
+        description: '',
+        methods: \[\],
+        displayName: 'IressButton',
+        props: {
+          value: {
+            required: false,
+            tsType: {
+              name: 'FormControlValue',
+            },
+            description: 'The value of the button, when used in \`IressButtonGroup\`.',
+          },
+          active: {
+            required: false,
+            tsType: {
+              name: 'boolean',
+            },
+            description: 'Sets the active state of the button, usually used to indicate the button has activated a modal, popover or slideout.',
+          },
+          append: {
+            required: false,
+            tsType: {
+              name: 'ReactNode',
+            },
+            description: 'Content for the append slot.',
+          },
+          children: {
+            required: false,
+            tsType: {
+              name: 'ReactNode',
+            },
+            description: 'Content is placed between prepend and append if provided. Used to describe the expected action of this button.',
+          },
+          element: {
+            required: false,
+            tsType: {
+              name: 'C',
+            },
+            description: 'Change the component that will be rendered as the button, used for third-party libraries that require a specific element type.\\nBy default, it will render a button or an anchor tag based on the \`href\` prop.',
+          },
+          fluid: {
+            required: false,
+            tsType: {
+              name: 'union',
+              raw: 'true | Breakpoints',
+              elements: \[
+                {
+                  name: 'literal',
+                  value: 'true',
+                },
+                {
+                  name: 'Breakpoints',
+                },
+              \],
+            },
+            description: "If \`true\`, the button will stretch to fill it's container. The prop is responsive, so you can set the breakpoint(s) at which the button will be fluid.\\n\\nAll breakpoints: \`fluid={true}\`\\nUp to a specific breakpoint: \`fluid={{ base: true, md: false }}\`",
+          },
+          href: {
+            required: false,
+            tsType: {
+              name: 'THref',
+            },
+            description: 'Contains a URL or a URL fragment that the hyperlink points to.\\nIf this property is set, an anchor tag will be rendered.',
+          },
+          loading: {
+            required: false,
+            tsType: {
+              name: 'union',
+              raw: 'boolean | string',
+              elements: \[
+                {
+                  name: 'boolean',
+                },
+                {
+                  name: 'string',
+                },
+              \],
+            },
+            description: 'When true, button is in loading state. If provided a string, will be used as the loading text for screen readers.',
+            defaultValue: {
+              value: 'false',
+              computed: false,
+            },
+          },
+          mode: {
+            required: false,
+            tsType: {
+              name: 'union',
+              raw: "'primary' | 'secondary' | 'tertiary'",
+              elements: \[
+                {
+                  name: 'literal',
+                  value: "'primary'",
+                },
+                {
+                  name: 'literal',
+                  value: "'secondary'",
+                },
+                {
+                  name: 'literal',
+                  value: "'tertiary'",
+                },
+              \],
+            },
+            description: 'Style of the button.\\n- Primary: Used for the main action on a page. Usually only used once per screen.\\n- Secondary: Used for secondary actions on a page, often an action on multiple \`IressPanel\`s. Can used multiple times per screen.\\n- Tertiary: Used for tertiary actions on a page, often the secondary action on multiple \`IressPanel\`s. Can used multiple times per screen.\\n\\n\*\*Migrating to version 6\*\*\\n- \`link\` mode has been removed. If it is an action, use the \`tertiary\` mode. If it is a link inside a paragraph, use the new \`IressLink\` component instead.\\n- \`danger\` has been removed. Please use the \`status\` prop instead.\\n- \`positive\` and \`success\` have been removed. Please use the \`status\` prop instead.',
+            defaultValue: {
+              value: "'secondary'",
+              computed: false,
+            },
+          },
+          onClick: {
+            required: false,
+            tsType: {
+              name: 'MouseEventHandler',
+              elements: \[
+                {
+                  name: 'Exclude',
+                  elements: \[
+                    {
+                      name: 'Parameters\[0\]',
+                      raw: 'Parameters<Exclude<ButtonRef<C, THref>, undefined>>\[0\]',
+                    },
+                    {
+                      name: 'null',
+                    },
+                  \],
+                  raw: 'Exclude<Parameters<Exclude<ButtonRef<C, THref>, undefined>>\[0\], null>',
+                },
+              \],
+              raw: 'MouseEventHandler<ButtonInstance<C, THref>>',
+            },
+            description: 'Emitted when the menu item is clicked.',
+          },
+          prepend: {
+            required: false,
+            tsType: {
+              name: 'ReactNode',
+            },
+            description: 'Content for the prepend slot.',
+          },
+          noWrap: {
+            required: false,
+            tsType: {
+              name: 'boolean',
+            },
+            description: 'Prevents text wrapping if set to true.',
+            defaultValue: {
+              value: 'false',
+              computed: false,
+            },
+          },
+          status: {
+            required: false,
+            tsType: {
+              name: 'union',
+              raw: "'success' | 'danger'",
+              elements: \[
+                {
+                  name: 'literal',
+                  value: "'success'",
+                },
+                {
+                  name: 'literal',
+                  value: "'danger'",
+                },
+              \],
+            },
+            description: 'An optional status to assign to the button.\\n- \`success\`: Indicates a successful or positive action.\\n- \`danger\`: Indicates a dangerous or potentially negative action.',
+          },
+        },
+        composes: \[
+          'IressCSSProps',
+          'IressTestProps',
+        \],
+      },
+    },
+    key: null,
+    props: {
+      type: 'submit',
+      mode: 'primary',
+      children: 'Submit',
+    },
+    \_owner: null,
+    \_store: {},
+  },
+  pattern: 'short',
+}}
+        onSubmit={() \=>
+          success({
+            heading: 'Passed validation',
+            content: JSON.stringify(formRef.current?.api.getValues(), null, 2),
+          })
+        }
+        onError={() \=>
+          error({
+            heading: 'Failed validation',
+            content: JSON.stringify(formRef.current?.api.getValues(), null, 2),
+          })
+        }
+        ref={formRef}
+      >        <IressFormField
+          label\="Name"
+          name\="name"
+          render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+          rules\={{
+            required: 'Name is required',
+          }}
+        />
+        <IressFormField
+          label\="Email address"
+          name\="email"
+          render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+          rules\={{
+            minLength: {
+              message: 'Use a longer email address',
+              value: 6,
+            },
+            required: 'Email is required',
+          }}
+        />
+      </IressForm\>
+      <IressDivider my\="md" />
+      <IressButton
+        onClick\={() \=> {
+          success({
+            heading: 'Saved as draft (no validation)',
+            content: JSON.stringify(formRef.current?.api.getValues(), null, 2),
+          });
+        }}
+      \>
+        Save as draft      </IressButton\>
+    </\>
+  );
+};
+export const DisableValidationForm \= () \=> (
+  <IressToasterProvider\>
+    <Form {...{
+  actions: {
+    type: {
+      \_\_docgenInfo: {
+        description: '',
+        methods: \[\],
+        displayName: 'IressButton',
+        props: {
+          value: {
+            required: false,
+            tsType: {
+              name: 'FormControlValue',
+            },
+            description: 'The value of the button, when used in \`IressButtonGroup\`.',
+          },
+          active: {
+            required: false,
+            tsType: {
+              name: 'boolean',
+            },
+            description: 'Sets the active state of the button, usually used to indicate the button has activated a modal, popover or slideout.',
+          },
+          append: {
+            required: false,
+            tsType: {
+              name: 'ReactNode',
+            },
+            description: 'Content for the append slot.',
+          },
+          children: {
+            required: false,
+            tsType: {
+              name: 'ReactNode',
+            },
+            description: 'Content is placed between prepend and append if provided. Used to describe the expected action of this button.',
+          },
+          element: {
+            required: false,
+            tsType: {
+              name: 'C',
+            },
+            description: 'Change the component that will be rendered as the button, used for third-party libraries that require a specific element type.\\nBy default, it will render a button or an anchor tag based on the \`href\` prop.',
+          },
+          fluid: {
+            required: false,
+            tsType: {
+              name: 'union',
+              raw: 'true | Breakpoints',
+              elements: \[
+                {
+                  name: 'literal',
+                  value: 'true',
+                },
+                {
+                  name: 'Breakpoints',
+                },
+              \],
+            },
+            description: "If \`true\`, the button will stretch to fill it's container. The prop is responsive, so you can set the breakpoint(s) at which the button will be fluid.\\n\\nAll breakpoints: \`fluid={true}\`\\nUp to a specific breakpoint: \`fluid={{ base: true, md: false }}\`",
+          },
+          href: {
+            required: false,
+            tsType: {
+              name: 'THref',
+            },
+            description: 'Contains a URL or a URL fragment that the hyperlink points to.\\nIf this property is set, an anchor tag will be rendered.',
+          },
+          loading: {
+            required: false,
+            tsType: {
+              name: 'union',
+              raw: 'boolean | string',
+              elements: \[
+                {
+                  name: 'boolean',
+                },
+                {
+                  name: 'string',
+                },
+              \],
+            },
+            description: 'When true, button is in loading state. If provided a string, will be used as the loading text for screen readers.',
+            defaultValue: {
+              value: 'false',
+              computed: false,
+            },
+          },
+          mode: {
+            required: false,
+            tsType: {
+              name: 'union',
+              raw: "'primary' | 'secondary' | 'tertiary'",
+              elements: \[
+                {
+                  name: 'literal',
+                  value: "'primary'",
+                },
+                {
+                  name: 'literal',
+                  value: "'secondary'",
+                },
+                {
+                  name: 'literal',
+                  value: "'tertiary'",
+                },
+              \],
+            },
+            description: 'Style of the button.\\n- Primary: Used for the main action on a page. Usually only used once per screen.\\n- Secondary: Used for secondary actions on a page, often an action on multiple \`IressPanel\`s. Can used multiple times per screen.\\n- Tertiary: Used for tertiary actions on a page, often the secondary action on multiple \`IressPanel\`s. Can used multiple times per screen.\\n\\n\*\*Migrating to version 6\*\*\\n- \`link\` mode has been removed. If it is an action, use the \`tertiary\` mode. If it is a link inside a paragraph, use the new \`IressLink\` component instead.\\n- \`danger\` has been removed. Please use the \`status\` prop instead.\\n- \`positive\` and \`success\` have been removed. Please use the \`status\` prop instead.',
+            defaultValue: {
+              value: "'secondary'",
+              computed: false,
+            },
+          },
+          onClick: {
+            required: false,
+            tsType: {
+              name: 'MouseEventHandler',
+              elements: \[
+                {
+                  name: 'Exclude',
+                  elements: \[
+                    {
+                      name: 'Parameters\[0\]',
+                      raw: 'Parameters<Exclude<ButtonRef<C, THref>, undefined>>\[0\]',
+                    },
+                    {
+                      name: 'null',
+                    },
+                  \],
+                  raw: 'Exclude<Parameters<Exclude<ButtonRef<C, THref>, undefined>>\[0\], null>',
+                },
+              \],
+              raw: 'MouseEventHandler<ButtonInstance<C, THref>>',
+            },
+            description: 'Emitted when the menu item is clicked.',
+          },
+          prepend: {
+            required: false,
+            tsType: {
+              name: 'ReactNode',
+            },
+            description: 'Content for the prepend slot.',
+          },
+          noWrap: {
+            required: false,
+            tsType: {
+              name: 'boolean',
+            },
+            description: 'Prevents text wrapping if set to true.',
+            defaultValue: {
+              value: 'false',
+              computed: false,
+            },
+          },
+          status: {
+            required: false,
+            tsType: {
+              name: 'union',
+              raw: "'success' | 'danger'",
+              elements: \[
+                {
+                  name: 'literal',
+                  value: "'success'",
+                },
+                {
+                  name: 'literal',
+                  value: "'danger'",
+                },
+              \],
+            },
+            description: 'An optional status to assign to the button.\\n- \`success\`: Indicates a successful or positive action.\\n- \`danger\`: Indicates a dangerous or potentially negative action.',
+          },
+        },
+        composes: \[
+          'IressCSSProps',
+          'IressTestProps',
+        \],
+      },
+    },
+    key: null,
+    props: {
+      type: 'submit',
+      mode: 'primary',
+      children: 'Submit',
+    },
+    \_owner: null,
+    \_store: {},
+  },
+  pattern: 'short',
+}} />  </IressToasterProvider\>
+);
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | \- |
+| onError | 
+
+\-
+
+ | \- | \- |
+| onSubmit | 
+
+\-
+
+ | \- | \- |
+| pattern | 
+
+string
+
+
+
+ | \- | short |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+### Resetting the form
+
+You can reset the form using the `ref` of the form. You must provide a `defaultValues` prop that contains all the fields in the form to ensure it resets properly.
+
+**Note:** `<button type="reset" />` does not work with `IressForm`. You need to add an `onClick` prop to the button and use the `ref.reset` method to reset the form.
+
+[](./iframe.html?id=patterns-form--reset-form)
+
+```
+
+import {
+  type IressFormProps,
+  IressForm,
+  type FormRef,
+  IressDivider,
+  IressButton,
+  IressFormField,
+  IressInput,
+} from '@iress-oss/ids-components';
+import { useRef } from 'react';
+interface FieldValues {
+  name?: string;
+  email?: string;
+}
+export const FormReset \= () \=> {
+  const ref \= useRef<FormRef<FieldValues\>>(null);
+  return (
+    <IressForm {...{
+  pattern: 'short',
+  defaultValues: {
+    name: '',
+    email: '',
+  },
+}} ref\={ref}\>
+      <IressFormField
+        label\="Name"
+        name\="name"
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{
+          required: 'Name is required',
+        }}
+      />
+      <IressFormField
+        label\="Email address"
+        name\="email"
+        render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+        rules\={{
+          minLength: {
+            message: 'Use a longer email address',
+            value: 6,
+          },
+          required: 'Email is required',
+        }}
+      />
+      <IressButton mode\="primary" type\="submit"\>
+        Sign up      </IressButton\>
+      <IressDivider my\="md" />
+      <IressButton type\="reset" onClick\={() \=> ref.current?.reset()}\>
+        Reset      </IressButton\>
+    </IressForm\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | \- |
+| pattern | 
+
+string
+
+
+
+ | \- | short |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+### Read only
+
+You can pass the `readOnly` prop to remove the asterisk symbol (\*) even when the field is `required`, and that field will be exempted from validation.
+
+[](./iframe.html?id=patterns-form--exclude-read-only-validation)
+
+```
+
+<IressStack gap\="md"\>
+  <IressText\>
+    <h2\>
+      Excludes read-only validation    </h2\>
+    <p\>
+      Try hitting submit to see that only email is being validated    </p\>
+  </IressText\>
+  <ForwardedForm
+    actions\={<IressButton mode\="primary" type\="submit"\>Submit</IressButton\>}
+    pattern\="short"
+  \>
+    <IressFormField
+      label\="Name"
+      name\="name"
+      readOnly
+      render\={() \=> {}}
+      rules\={{
+        required: 'Name is required'
+      }}
+    />
+    <IressFormField
+      label\="Email address"
+      name\="email"
+      render\={() \=> {}}
+      rules\={{
+        minLength: {
+          message: 'Use a longer email address',
+          value: 6
+        },
+        required: 'Email is required'
+      }}
+    />
+  </ForwardedForm\>
+</IressStack\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+\-
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| pattern | 
+
+string
+
+
+
+ | \- | short |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+`IressHookForm`
+---------------
+
+`IressHookForm` is the underlying component that `IressForm` is built upon. It has a single required prop, `form`, which expects the return value of the `useForm` hook from React Hook Forms.
+
+It has been exposed to consumers to allow you to have complete control of your React Hook Forms instance whilst still taking advantage of the IDS form components.
+
+Some use cases:
+
+1.  You may need to use the `useForm` hook in a parent component to share the form state with multiple child components.
+2.  You would like to use the return value of the `useForm` hook without having to use a ref to access the `react-hook-form` api.
+
+[](./iframe.html?id=patterns-form--hook-form)
+
+```
+
+interface FieldValues {
+  firstName: string;
+  lastName: string;
+  insuredAtPolicyLevel?: boolean;
+  sumInsured?: number;
+  sumInsured\_na?: string;
+}
+export const HookFormExample \= () \=> {
+  const initialInsuredAtPolicyLevel \= false;
+  const initialSumInsured \= 5000;
+  const form \= IressHookForm.useForm<FieldValues\>();
+  const { watch, control } \= form;
+  const firstName \= watch('firstName');
+  const lastName \= watch('lastName');
+  const insuredAtPolicyLevel \= watch('insuredAtPolicyLevel');
+  return (
+    <IressContainer\>
+      <IressText\>
+        <h2\>Hook Form Example</h2\>
+        <p\>
+          This example demonstrates how to use the <code\>IressHookForm</code\>{' '}
+          component to create a form with controlled fields and conditional          rendering based on form values.        </p\>
+        <IressHookForm form\={form}\>
+          {firstName && lastName && (
+            <IressPanel mb\="md" bg\="alt"\>
+              Name: {firstName} {lastName}
+            </IressPanel\>
+          )}
+          <IressFormField
+            name\="firstName"
+            label\="First Name"
+            render\={(controlledProps) \=> <IressInput {...controlledProps} />}
+            rules\={{ required: true }}
+          />
+          <IressFormField
+            name\="lastName"
+            label\="Last Name"
+            render\={(controlledProps) \=> (
+              <IressInput {...controlledProps} type\="email" />
+            )}
+            rules\={{ required: true }}
+          />
+          <IressDivider mt\="lg" mb\="md" />
+          <IressFormField
+            name\="insuredAtPolicyLevel"
+            defaultChecked\={initialInsuredAtPolicyLevel}
+            label\="Insurance options"
+            control\={control}
+            render\={(controlledProps) \=> (
+              <IressCheckbox {...controlledProps}\>
+                Insured at policy level              </IressCheckbox\>
+            )}
+          />
+          {insuredAtPolicyLevel && (
+            <IressFormField
+              name\="sumInsured"
+              defaultValue\={initialSumInsured}
+              label\="Sum insured"
+              control\={control}
+              render\={(controlledProps) \=> (
+                <IressInputCurrency {...controlledProps} currencyCode\="GBP" />
+              )}
+            />
+          )}
+          {!insuredAtPolicyLevel && (
+            <IressFormField
+              name\="sumInsured\_na"
+              defaultValue\="N/A"
+              label\="Sum insured"
+              control\={control}
+              render\={(properties) \=> <IressInput {...properties} readOnly />}
+            />
+          )}
+          <IressButton type\="submit" mode\="primary"\>
+            Submit          </IressButton\>
+        </IressHookForm\>
+      </IressText\>
+    </IressContainer\>
+  );
+};
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| alert | 
+The content of the alert section.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| children | 
+
+The content of the form, usually multiple `IressFormField` or `IressFormFieldset` components.
+
+ReactNode
+
+
+
+ | \- | Set object |
+| form\* | 
+
+React hook form instance.
+
+UseFormReturn
+
+
+
+ | \- | Set object |
+| onError | 
+
+Emitted when any field has an error. Called after the first submit if any errors are recorded, and from then on when any value changes.
+
+SubmitErrorHandler
+
+
+
+ | \- | Set object |
+| onSubmit | 
+
+Handler for when the submit method on the form is called after validation is passed.
+
+(data: T) => void
+
+ | \- | \- |
+| onValidChange | 
+
+Emitted when the form state is valid.
+
+(isValid: boolean) => void
+
+ | \- | \- |
+| updateErrorSummaryOnSubmit | 
+
+If set to `true`, the summary will only update when the form is submitted, not on every field change. This is useful for performance reasons, especially in large forms.
+
+boolean
+
+
+
+ | \- | Set boolean |
+
+`IressFormValidationSummary`
+----------------------------
+
+`IressFormValidationSummary` is the error summary component that is added to the top of the form for screen readers to announce validation errors. It is automatically added to the form when there are validation errors, but you can also use it independently to create your own error summary, usually used if you want a visible error summary at the top of the form.
+
+[](./iframe.html?id=patterns-form--validation-summary)
+
+```
+
+<ForwardedForm
+  actions\={<IressButton mode\="primary" type\="submit"\>Submit</IressButton\>}
+  alert\={<IressFormValidationSummary />}
+  heading\="Try hitting submit to see the validation summary"
+  pattern\="long"
+\>
+  <IressText element\="p"\>
+    This form showcases all the different components you can use within{' '}
+    <code\>
+      IressFormField    </code\>
+    .  </IressText\>
+  <IressFormField
+    label\="Name"
+    name\="name"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="Date"
+    name\="date"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="Gender"
+    name\="gender"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="Gender with icons"
+    name\="gender-with-icons"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormFieldset
+    label\="Hobbies"
+    name\="hobbies"
+    render\={() \=> {}}
+    rules\={{
+      required: 'Select at least one hobby'
+    }}
+  />
+  <IressFormFieldset
+    label\="Food of preference"
+    name\="food"
+    render\={() \=> {}}
+    rules\={{
+      required: 'Select at least one food of preference'
+    }}
+  />
+  <IressFormField
+    label\="Terms and privacy policy"
+    name\="terms"
+    render\={() \=> {}}
+    rules\={{
+      required: 'You need to agree to the terms and conditions before proceeding'
+    }}
+  />
+  <IressFormField
+    hint\="Type to copy an existing character's name"
+    label\="Your star wars name"
+    name\="star\_wars\_name"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="What's your pain level?"
+    name\="pain\_level"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+  <IressFormField
+    label\="Favourite email domains"
+    name\="email\_domains"
+    render\={() \=> {}}
+    rules\={{
+      required: true
+    }}
+  />
+</ForwardedForm\>
+
+```
+
+#### Props
+
+| Name | Description | Default | Control |
+| --- | --- | --- | --- |
+| actions | 
+object
+
+
+
+ | \- | Choose option...nonesubmitsave |
+| alert | 
+
+object
+
+
+
+ | \- | Choose option...nonebasicAlert |
+| children | 
+
+array
+
+
+
+ | \- | Choose option...nonesimplesupportedControlsreadOnly |
+| heading | 
+
+string
+
+
+
+ | \- | Try hitting submit to see the validation summary |
+| pattern | 
+
+string
+
+
+
+ | \- | long |
+| Show React Hook Forms itemsReact Hook Forms | Show React Hook Forms items |
+
+Migration to version 5 and beyond
+---------------------------------
+
+The previous form components contained a lot of logic to translate the HTML5 validation API to a format that matched the design system’s guidelines. This allowed users to use the default props of input such as `pattern` and `required`, and be assured that the `IressField` would display errors accordingly.
+
+Although this worked for simple forms, it did not work for forms which had complex business requirements. This was due to the logic inside the form components being hard to override. Additionally, it was seemingly impossible to implement the business requirements using the HTML5 validation API, which itself is very restricted.
+
+In version 5 we have decided to provide two alternative methods of using form components to better accommodate our consumer’s needs.
+
+The validation logic has been stripped from all of the existing form components. They are now closer to their native implementation, with a few customisations to match the IDS guidelines. IressField has transformed into a layout component to allow you to lay out form fields consistent with IDS guidelines, using your own validation tools.
+
+Automated validation is now solely contained in `IressForm` and `IressFormField`, using [React Hook Form](https://react-hook-form.com/docs/useform) under the hood to simplify maintenance.
+
+Testing
+-------
+
+Unfortunately due to the asynchronous nature of React Hook Form validation, `IressForm` still needs to be tested using `screen.findBy` queries (at least in the first query after render). If `findBy` is not used, you will start to see the dreaded `act warnings`. For more information on testing IressForm, please refer to the (React Hook Form testing documentation)\[[https://react-hook-form.com/advanced-usage#TestingForm](https://react-hook-form.com/advanced-usage#TestingForm)\]
+
+Here is an example of testing a form submission.
+
+render(
+  <IressForm\>
+    <IressFormField
+      label\="Email"
+      name\="email"
+      rules\={{ required: true }}
+      render\={(controlledProps) \=> (
+        <IressInput {...controlledProps} type\="email" />
+      )}
+    />
+    <IressButton type\="submit"\>Submit</IressButton\>
+  </IressForm\>,
+);
+// May be needed sometimes to get over the act warning
+await screen.getByRole('form');
+const emailInput \= screen.getByRole('textbox');
+const submitButton \= screen.getByRole('button', { name: 'Submit' });
+await userEvent.click(submitButton);
+// Errors are asynchronous, so we need to wait for them to appear
+const summaryError \= await screen.findByText(
+  'There was a problem submitting this form',
+);
+expect(summaryError).toBeInTheDocument();
+
+```
+
+Caveat
+------
+
+### Using `IressSelect` with non-string values in `IressFormField`
+
+When using form controls that support non-string values (like `IressSelect` with number values), you might encounter type conflicts with React Hook Form's default event handling. By default, React Hook Form expects string values from form controls.
+
+**Problem:**
+
+<IressFormField
+  name\="dependents"
+  label\="Dependents"
+  render\={(controlledProps) \=> (
+    <IressSelect {...controlledProps}\>
+      <option key\="0" value\={0}\>
+        0      </option\>
+      <option key\="1" value\={1}\>
+        1      </option\>
+      <option key\="2" value\={2}\>
+        2      </option\>
+    </IressSelect\>
+  )}
+/>
+
+```
+
+In this case, React Hook Form will try to convert the value to string, which might cause type issues.
+
+**Solution:** Override the `onChange` handler to pass the actual value as a second parameter:
+
+<IressFormField
+  name\="dependents"
+  label\="Dependents"
+  render\={(controlledProps) \=> (
+    <IressSelect
+      {...controlledProps}
+      onChange\={(\_e, value) \=> controlledProps.onChange(value)}
+    \>
+      <option key\="0" value\={0}\>
+        0      </option\>
+      <option key\="1" value\={1}\>
+        1      </option\>
+      <option key\="2" value\={2}\>
+        2      </option\>
+    </IressSelect\>
+  )}
+/>
+
+```
+
+This ensures the original value type is preserved when passed to React Hook Form. You can find out more about the code example in the [Switch Edit Readonly Form Documentation](?path=/docs/components-form-recipes--docs#switching-between-readonly-and-edit-modes).
+
+### Properly resetting fields
+
+When resetting fields that accept non-string values (like `IressRichSelect`), you should reset them to `null` or `undefined` instead of an empty string. This is because the underlying component is strictly typed and expects a specific value type.
+
+**Problem:**
+
+const { resetField } \= IressForm.useFormContext();
+resetField('rich-select', {
+  label: '',
+  value: '',
+});
+
+```
+
+In this case, it will look like it cleared the field, but actually it has not. This is obvious with a `placeholder` set, as it will not show the placeholder.
+
+**Solution:** Override the `onChange` handler to pass the actual value as a second parameter:
+
+const { resetField } \= IressForm.useFormContext();
+resetField('rich-select', null); // or undefined
+
+```
+
+This will properly reset the field to null and clear the field value.
+
+### Conflicting versions of React Hook Forms
+
+If you are using React Hook Forms in your application, please ensure it is the same version IDS uses, otherwise there will be conflicts.
+
+The version we are using in IDS is:
+
+yarn add react-hook-form@7.55.0