diff --git a/docs/guides/form-errors.md b/docs/guides/forms.md similarity index 77% rename from docs/guides/form-errors.md rename to docs/guides/forms.md index e11b1e3010..c17a897737 100644 --- a/docs/guides/form-errors.md +++ b/docs/guides/forms.md @@ -1,11 +1,35 @@ --- -title: Form Errors +title: Forms category: Guides order: 4 relevantForAI: true --- -# Adding Error Messages to Form Components +## Required Fields + +InstUI form components display an asterisk (`*`) next to labels when the `isRequired` (or `required`) prop is set. Whenever a form contains required fields, you **must include a note** explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required." + +> **Exception:** You can omit this note when the form's purpose is entirely self-evident — for example, a standard login screen where it is obvious that both the email and password fields are required. + +```ts +--- +type: example +--- +const RequiredFieldsExample = () => { + return ( + + Fields marked with an asterisk are required. + + + + + ) +} + +render() +``` + +## Error Messages InstUI offers a range of form elements and all of them have a similar API to handle error/hint/success messages. These components use the `messages` prop with the following type definition: @@ -86,6 +110,8 @@ const Example = () => {
+ {isRequired && Fields marked with an asterisk are required.} + @@ -138,6 +164,11 @@ const Example = () => { invalidDateTimeMessage="Invalid date!" prevMonthLabel="Previous month" nextMonthLabel="Next month" + screenReaderLabels={{ + calendarIcon: 'Open calendar', + prevMonthButton: 'Previous month', + nextMonthButton: 'Next month' + }} defaultValue="2018-01-18T13:30" layout="columns" isRequired={isRequired} @@ -152,6 +183,11 @@ const Example = () => { invalidDateTimeMessage="Invalid date!" prevMonthLabel="Previous month" nextMonthLabel="Next month" + screenReaderLabels={{ + calendarIcon: 'Open calendar', + prevMonthButton: 'Previous month', + nextMonthButton: 'Next month' + }} defaultValue="2018-01-18T13:30" layout="stacked" isRequired={isRequired} diff --git a/packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json b/packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json index 5a3b891137..10c97fd390 100644 --- a/packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json +++ b/packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json @@ -433,7 +433,7 @@ "summary": "Comprehensive focus management system for dialogs, modals, and popovers. Uses Dialog component with FocusRegion and FocusRegionManager to trap focus, handle escape keys, and manage screen reader accessibility." }, { - "title": "form-errors", + "title": "forms", "summary": "InstUI form components use a `messages` prop for error/hint/success messages. Required fields now show an asterisk automatically. Examples provided for various form components like TextInput, Checkbox, and DateTimeInput." }, { diff --git a/packages/ui-checkbox/src/Checkbox/v1/README.md b/packages/ui-checkbox/src/Checkbox/v1/README.md index 386de0c2ab..1c3ebea391 100644 --- a/packages/ui-checkbox/src/Checkbox/v1/README.md +++ b/packages/ui-checkbox/src/Checkbox/v1/README.md @@ -162,6 +162,20 @@ type: example /> ``` +### Required Fields + +Whenever a `Checkbox` is required, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required." + +```js +--- +type: example +--- + + Fields marked with an asterisk are required. + + +``` + ### Guidelines ```js diff --git a/packages/ui-checkbox/src/Checkbox/v2/README.md b/packages/ui-checkbox/src/Checkbox/v2/README.md index 458d43f1cb..73f5fd87d3 100644 --- a/packages/ui-checkbox/src/Checkbox/v2/README.md +++ b/packages/ui-checkbox/src/Checkbox/v2/README.md @@ -166,6 +166,20 @@ type: example The underlying `` has a `data-checked` attribute (`"true"`, `"false"`, or `"mixed"` when indeterminate) that can be queried from the DOM to read the current state. +### Required Fields + +Whenever a `Checkbox` is required, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required." + +```js +--- +type: example +--- + + Fields marked with an asterisk are required. + + +``` + ### Guidelines ```js diff --git a/packages/ui-color-picker/src/ColorPicker/v1/README.md b/packages/ui-color-picker/src/ColorPicker/v1/README.md index 72427486e6..431993322d 100644 --- a/packages/ui-color-picker/src/ColorPicker/v1/README.md +++ b/packages/ui-color-picker/src/ColorPicker/v1/README.md @@ -201,6 +201,7 @@ type: example return ( + {isRequired && Fields marked with an asterisk are required.} setValue(val)} value={value} diff --git a/packages/ui-color-picker/src/ColorPicker/v2/README.md b/packages/ui-color-picker/src/ColorPicker/v2/README.md index fe2e7f64c8..5cff0f16f2 100644 --- a/packages/ui-color-picker/src/ColorPicker/v2/README.md +++ b/packages/ui-color-picker/src/ColorPicker/v2/README.md @@ -201,6 +201,7 @@ type: example return ( + {isRequired && Fields marked with an asterisk are required.} setValue(val)} value={value} diff --git a/packages/ui-date-time-input/src/DateTimeInput/v1/README.md b/packages/ui-date-time-input/src/DateTimeInput/v1/README.md index 26cdaa6d3a..80a4cd2145 100644 --- a/packages/ui-date-time-input/src/DateTimeInput/v1/README.md +++ b/packages/ui-date-time-input/src/DateTimeInput/v1/README.md @@ -82,6 +82,7 @@ type: example
{text}
+ Fields marked with an asterisk are required.
``` +### Required Fields + +Whenever a `FormFieldGroup` contains required fields, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required." + +```js +--- +type: example +--- + + Fields marked with an asterisk are required. + + + + +``` + ### Guidelines ```js diff --git a/packages/ui-form-field/src/FormFieldGroup/v2/README.md b/packages/ui-form-field/src/FormFieldGroup/v2/README.md index a057b5449c..b0c2a37ab7 100644 --- a/packages/ui-form-field/src/FormFieldGroup/v2/README.md +++ b/packages/ui-form-field/src/FormFieldGroup/v2/README.md @@ -100,6 +100,26 @@ type: example ``` +### Required Fields + +Whenever a `FormFieldGroup` contains required fields, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required." + +```js +--- +type: example +--- + + Fields marked with an asterisk are required. + + + + +``` + ### Guidelines ```js diff --git a/packages/ui-number-input/src/NumberInput/v1/README.md b/packages/ui-number-input/src/NumberInput/v1/README.md index b34ff86a0b..4123fe6800 100644 --- a/packages/ui-number-input/src/NumberInput/v1/README.md +++ b/packages/ui-number-input/src/NumberInput/v1/README.md @@ -125,6 +125,7 @@ const Example = () => { label="Inline display" onChange={toggleInline} /> + Fields marked with an asterisk are required. { label="Inline display" onChange={toggleInline} /> + Fields marked with an asterisk are required. ``` +### Required Fields + +Whenever a `RadioInputGroup` contains required fields, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required." + +```js +--- +type: example +--- + + Fields marked with an asterisk are required. + + + + + + +``` + ### Guidelines ```js diff --git a/packages/ui-radio-input/src/RadioInputGroup/v2/README.md b/packages/ui-radio-input/src/RadioInputGroup/v2/README.md index c51623ab29..ad51d97f5d 100644 --- a/packages/ui-radio-input/src/RadioInputGroup/v2/README.md +++ b/packages/ui-radio-input/src/RadioInputGroup/v2/README.md @@ -220,6 +220,24 @@ type: example ``` +### Required Fields + +Whenever a `RadioInputGroup` contains required fields, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required." + +```js +--- +type: example +--- + + Fields marked with an asterisk are required. + + + + + + +``` + ### Guidelines ```js diff --git a/packages/ui-text-area/src/TextArea/v1/README.md b/packages/ui-text-area/src/TextArea/v1/README.md index 288815c233..3432bb1e1f 100644 --- a/packages/ui-text-area/src/TextArea/v1/README.md +++ b/packages/ui-text-area/src/TextArea/v1/README.md @@ -102,6 +102,18 @@ type: example render() ``` +A required `TextArea`: + +```js +--- +type: example +--- + + Fields marked with an asterisk are required. +