Skip to content
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

Docs: add a11y guidance regarding required fields #878

Merged
merged 2 commits into from
Nov 1, 2024
Merged

Docs: add a11y guidance regarding required fields #878

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2f80f36
Docs: add a11y guidance regarding required fields
francinelucca Oct 17, 2024
01f7bcf
Update content/ui-patterns/forms/overview.mdx
francinelucca Oct 18, 2024
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
2 changes: 1 addition & 1 deletion content/components/checkbox.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Checkboxes are capable of showing two forms of selection: checked (left) or inde
### Best practices

- An individual checkbox should not have its own validation message or style. Instead, show a validation message on the [checkbox group](/components/checkbox-group). For more information, see the [Validation Message](../ui-patterns/forms/overview#validation) section in the Forms documentation.
- An individual checkbox button cannot be marked as required. Instead, make a selection required using the [checkbox group](/components/checkbox-group). For more information, see the [Required field indicator](../ui-patterns/forms/overview#required-field-indicator) in the Forms documentation.
- While there are certain use cases where an individual checkbox may be required, the most common use case is to require a selection from a [checkbox group](/components/checkbox-group). In this case, an individual checkbox button should not be marked as required, but the checkbox group should be marked as required instead. For more information, see the [Required field indicator](../ui-patterns/forms/overview#required-field-indicator) in the Forms documentation.

## Accessibility

Expand Down
28 changes: 28 additions & 0 deletions content/components/form-control.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ description: Form control displays a labelled input and, optionally, associated
reactId: form_control
---

import Code from '@primer/gatsby-theme-doctocat/src/components/code'
import ComponentLayout from '~/src/layouts/component-layout'
export default ComponentLayout
import {AccessibilityLink} from '~/src/components/accessibility-link'
Expand All @@ -28,6 +29,33 @@ To learn more about anatomy, input methods, forms structure, validation, and mor

When using symbols -e.g., an asterisk (*)- to indicate particular fields are required within a form, consider adding a "Required fields are marked with an asterisk (\*)" message at the top of the form for extra clarity.

When marking a control as required, opt to mark the form control as required instead of the input contained within it. The form control will ensure that the required state is passed down to the input element.

<DoDontContainer>
<Do>
<Code classname="language-jsx">{`
<FormControl required>
<FormControl.Label>
Form Input Label
</FormControl.Label>
<Checkbox />
</FormControl>
`}</Code>
<Caption>Set the required field in the form control</Caption>
</Do>
<Dont>
<Code classname="language-jsx">{`
<FormControl>
<FormControl.Label>
Form Input Label
</FormControl.Label>
<Checkbox required />
</FormControl>
`}</Code>
<Caption>Don’t set the required field on the underlying input</Caption>
</Dont>
</DoDontContainer>

### Known accessibility issues (GitHub staff only)

<AccessibilityLink label="FormControl"/>
Expand Down
78 changes: 77 additions & 1 deletion content/ui-patterns/forms/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ current_page: overview
---

import {Box, Heading} from '@primer/react'
import Code from '@primer/gatsby-theme-doctocat/src/components/code'
import FormsLayout from '~/src/layouts/forms-layout'
export default FormsLayout

Expand Down Expand Up @@ -35,7 +36,82 @@ This guidance applies to situations where all fields are required. The exception

Fields visually marked as required should also be set as required in code. This creates a parity in experience for all users.

An individual checkbox or radio button cannot be marked as required.
When marking a field as required, opt to mark the [form control](/components/form-control) as required instead of the input contained within it. The [form control](/components/form-control) will ensure that the required state is passed down to the input element.

<DoDontContainer>
<Do>
<Code classname="language-jsx">{`
<FormControl required>
<FormControl.Label>
Form Input Label
</FormControl.Label>
<Checkbox />
</FormControl>
`}</Code>
<Caption>Set the required field in the form control</Caption>
</Do>
<Dont>
<Code classname="language-jsx">{`
<FormControl>
<FormControl.Label>
Form Input Label
</FormControl.Label>
<Checkbox required />
</FormControl>
`}</Code>
<Caption>Don’t set the required field on the underlying input</Caption>
</Dont>
</DoDontContainer>

An individual radio button cannot be marked as required. You may indicate a required selection within a [radio group](/components/radio-group).

<DoDontContainer>
<Do>
<Code classname="language-jsx">{`
<RadioGroup name="radioGroup" required>
<RadioGroup.Label>
Radio Group Label
</RadioGroup.Label>
<FormControl>
<Radio value="one" />
<FormControl.Label>
Choice one
</FormControl.Label>
</FormControl>
<FormControl>
<Radio value="two" defaultChecked />
<FormControl.Label>
Choice two
</FormControl.Label>
</FormControl>
</RadioGroup>`}</Code>
<Caption>Set the required field in the radio group</Caption>
</Do>
<Dont>
<Code classname="language-jsx">{`
<RadioGroup name="radioGroup">
<RadioGroup.Label>
Radio Group Label
</RadioGroup.Label>
<FormControl>
<Radio value="one" required />
<FormControl.Label>
Choice one
</FormControl.Label>
</FormControl>
<FormControl>
<Radio value="two" defaultChecked />
<FormControl.Label>
Choice two
</FormControl.Label>
</FormControl>
</RadioGroup>
`}</Code>
<Caption>Don’t set the required field on an individual radio</Caption>
</Dont>
</DoDontContainer>

Individual checkboxes may be marked as required, as well as [checkbox groups](/components/checkbox-group).

### Input (required)

Expand Down
Loading