Skip to content

docs(many): add required field examples and * required field note to … #2515

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ToMESSKa merged 1 commit into from
May 7, 2026
Merged

docs(many): add required field examples and * required field note to … #2515

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 38 additions & 2 deletions docs/guides/form-errors.md → docs/guides/forms.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,35 @@
---
title: Form Errors
title: Forms

@balzss balzss May 7, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

small thing but you've changed the title but didn't change the filename (and in turn the slug of the doc). would be more consistent that way, other than that everything is fine

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 (
<FormFieldGroup description="Contact Information" rowSpacing="small" layout="stacked">
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<TextInput renderLabel="Full Name" isRequired />
<TextInput renderLabel="Email Address" isRequired />
<TextInput renderLabel="Phone Number" />
</FormFieldGroup>
)
}

render(<RequiredFieldsExample />)
```

## 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:

Expand Down Expand Up @@ -86,6 +110,8 @@ const Example = () => {
</CheckboxGroup>
<div style={{display: 'flex', gap: '2rem', marginTop: '3rem', flexDirection: 'column'}}>

{isRequired && <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>}

<TextInput renderLabel="TextInput" messages={messages} isRequired={isRequired}/>

<NumberInput renderLabel="NumberInput" messages={messages} isRequired={isRequired}/>
Expand Down Expand Up @@ -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}
Expand All @@ -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}
Expand Down
2 changes: 1 addition & 1 deletion packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
},
{
Expand Down
14 changes: 14 additions & 0 deletions packages/ui-checkbox/src/Checkbox/v1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
---
<FormFieldGroup description="Terms" rowSpacing="small" layout="stacked">
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<Checkbox label="I agree to the terms and conditions" value="terms" isRequired />
</FormFieldGroup>
```

### Guidelines

```js
Expand Down
14 changes: 14 additions & 0 deletions packages/ui-checkbox/src/Checkbox/v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,20 @@ type: example

The underlying `<input>` 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
---
<FormFieldGroup description="Terms" rowSpacing="small" layout="stacked">
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<Checkbox label="I agree to the terms and conditions" value="terms" isRequired />
</FormFieldGroup>
```

### Guidelines

```js
Expand Down
1 change: 1 addition & 0 deletions packages/ui-color-picker/src/ColorPicker/v1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,7 @@ type: example

return (
<View as="div">
{isRequired && <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>}
<ColorPicker
onChange={(val) => setValue(val)}
value={value}
Expand Down
1 change: 1 addition & 0 deletions packages/ui-color-picker/src/ColorPicker/v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,7 @@ type: example

return (
<View as="div">
{isRequired && <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>}
<ColorPicker
onChange={(val) => setValue(val)}
value={value}
Expand Down
1 change: 1 addition & 0 deletions packages/ui-date-time-input/src/DateTimeInput/v1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ type: example
<br />
{text}
</div>
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<div style={{ height: '14rem' }}>
<DateTimeInput
description={
Expand Down
20 changes: 20 additions & 0 deletions packages/ui-form-field/src/FormFieldGroup/v1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,26 @@ type: example
</FormFieldGroup>
```

### 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
---
<FormFieldGroup
description="Contact Information"
rowSpacing="small"
layout="stacked"
>
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<TextInput renderLabel="Full Name" isRequired />
<TextInput renderLabel="Email Address" isRequired />
<TextInput renderLabel="Phone Number" />
</FormFieldGroup>
```

### Guidelines

```js
Expand Down
20 changes: 20 additions & 0 deletions packages/ui-form-field/src/FormFieldGroup/v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,26 @@ type: example
</FormFieldGroup>
```

### 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
---
<FormFieldGroup
description="Contact Information"
rowSpacing="small"
layout="stacked"
>
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<TextInput renderLabel="Full Name" isRequired />
<TextInput renderLabel="Email Address" isRequired />
<TextInput renderLabel="Phone Number" />
</FormFieldGroup>
```

### Guidelines

```js
Expand Down
1 change: 1 addition & 0 deletions packages/ui-number-input/src/NumberInput/v1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ const Example = () => {
label="Inline display"
onChange={toggleInline}
/>
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<NumberInput
renderLabel={`How old are you? (${MIN}-${MAX})`}
display={inline ? 'inline-block' : null}
Expand Down
1 change: 1 addition & 0 deletions packages/ui-number-input/src/NumberInput/v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@ const Example = () => {
label="Inline display"
onChange={toggleInline}
/>
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<NumberInput
renderLabel={`How old are you? (${MIN}-${MAX})`}
display={inline ? 'inline-block' : null}
Expand Down
18 changes: 18 additions & 0 deletions packages/ui-radio-input/src/RadioInputGroup/v1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -220,6 +220,24 @@ type: example
</RadioInputGroup>
```

### 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
---
<FormFieldGroup description="Preferences" rowSpacing="small" layout="stacked">
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<RadioInputGroup name="frequency" description="Notification Frequency" isRequired>
<RadioInput label="Daily" value="daily" />
<RadioInput label="Weekly" value="weekly" />
<RadioInput label="Monthly" value="monthly" />
</RadioInputGroup>
</FormFieldGroup>
```

### Guidelines

```js
Expand Down
18 changes: 18 additions & 0 deletions packages/ui-radio-input/src/RadioInputGroup/v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -220,6 +220,24 @@ type: example
</RadioInputGroup>
```

### 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
---
<FormFieldGroup description="Preferences" rowSpacing="small" layout="stacked">
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<RadioInputGroup name="frequency" description="Notification Frequency" isRequired>
<RadioInput label="Daily" value="daily" />
<RadioInput label="Weekly" value="weekly" />
<RadioInput label="Monthly" value="monthly" />
</RadioInputGroup>
</FormFieldGroup>
```

### Guidelines

```js
Expand Down
12 changes: 12 additions & 0 deletions packages/ui-text-area/src/TextArea/v1/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,18 @@ type: example
render(<Example />)
```

A required `TextArea`:

```js
---
type: example
---
<View as="div">
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<TextArea label="Description" required />
</View>
```

### Guidelines

```js
Expand Down
12 changes: 12 additions & 0 deletions packages/ui-text-area/src/TextArea/v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,18 @@ type: example
render(<Example />)
```

A required `TextArea`:

```js
---
type: example
---
<View as="div">
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<TextArea label="Description" required />
</View>
```

### Guidelines

```js
Expand Down
8 changes: 8 additions & 0 deletions packages/ui-text-input/src/TextInput/v2/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -317,6 +317,14 @@ type: example
placeholder="placeholder"
size='small'
/>
<View as="div">
<Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
<TextInput
renderLabel='required'
placeholder="placeholder"
isRequired
/>
</View>
</Flex>
```

Expand Down
Loading