Skip to content

Commit 9c7cb09

Browse files
committed
docs(ui): document Field labels for controls without a native label
1 parent 6ff08ed commit 9c7cb09

4 files changed

Lines changed: 54 additions & 2 deletions

File tree

‎packages/swingset/src/stories/field.component.mdx‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ import * as FieldStories from './field.component.stories';
1111

1212
## Usage
1313

14-
Compose one Mosaic control inside each `Field.Root` to generate its ID, the label's `htmlFor`, and the message relationships. Rendering multiple controls logs a development warning. The caller owns validation and decides when to render an error. Use a separate `Field.Root` for each control; grouped controls should use native `<fieldset>` and `<legend>` semantics until dedicated Mosaic `Fieldset` and `Field.Item` components are available.
14+
Compose one Mosaic control inside each `Field.Root` to generate its ID, the label relationship, and the message relationships. Rendering multiple controls logs a development warning. The caller owns validation and decides when to render an error. Use a separate `Field.Root` for each control; grouped controls should use native `<fieldset>` and `<legend>` semantics until dedicated Mosaic `Fieldset` and `Field.Item` components are available.
1515

1616
```tsx
1717
import { Field } from '@clerk/ui/mosaic/components/field';
@@ -42,6 +42,20 @@ Field does not validate controls or render errors automatically. Its parts may a
4242

4343
Pass `visuallyHidden` to `Field.Label` when the surrounding UI already makes the label redundant. The label is still rendered and still associated with the control, so the control keeps its accessible name — unlike dropping the label and relying on a `placeholder`, which is not an accessible name. It applies the same style as the [VisuallyHidden](/components/visually-hidden) component.
4444

45+
### Controls without a native label
46+
47+
<Story
48+
name='WithSelect'
49+
storyModule={FieldStories}
50+
/>
51+
52+
A native `<label>` activates the control it names, which for a `Select` trigger would open the
53+
listbox on every label click. A control that cannot be natively labelled registers as such, and
54+
`Field.Label` then renders a `span` instead: clicking it focuses the control, and the control is named
55+
through `aria-labelledby` rather than `htmlFor`. Description and error relationships are unchanged.
56+
Explicit `htmlFor` still renders a native `label`. `Select.Trigger` opts in; `Input` and `OTP` keep
57+
the native label.
58+
4559
## Parts
4660

4761
| Part | Stable slot class | Description |

‎packages/swingset/src/stories/field.component.stories.tsx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import { Field } from '@clerk/ui/mosaic/components/field';
22
import { Input } from '@clerk/ui/mosaic/components/input';
3+
import { Select } from '@clerk/ui/mosaic/components/select';
34

45
import type { StoryMeta } from '@/lib/types';
56

@@ -46,3 +47,24 @@ export function VisuallyHiddenLabel() {
4647
</Field.Root>
4748
);
4849
}
50+
51+
const roles = [
52+
{ value: 'member', label: 'Member' },
53+
{ value: 'admin', label: 'Admin' },
54+
];
55+
56+
export function WithSelect() {
57+
return (
58+
<Field.Root style={stackStyles}>
59+
<Field.Label>Role</Field.Label>
60+
<Select.Root
61+
items={roles}
62+
defaultValue='member'
63+
>
64+
<Select.Trigger />
65+
<Select.Popup />
66+
</Select.Root>
67+
<Field.Description>Applies to new members of the organization.</Field.Description>
68+
</Field.Root>
69+
);
70+
}

‎packages/ui/src/mosaic/components/field/field.test.tsx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -396,6 +396,22 @@ describe('Mosaic Field', () => {
396396
consoleWarn.mockRestore();
397397
});
398398

399+
it('keeps a native label for a select when htmlFor is explicit', () => {
400+
render(
401+
<Field.Root>
402+
<Field.Label htmlFor='elsewhere'>Role</Field.Label>
403+
<Select.Root items={[{ value: 'admin', label: 'Admin' }]}>
404+
<Select.Trigger />
405+
<Select.Popup />
406+
</Select.Root>
407+
</Field.Root>,
408+
);
409+
410+
const label = screen.getByText('Role');
411+
expect(label.tagName).toBe('LABEL');
412+
expect(label).toHaveAttribute('for', 'elsewhere');
413+
});
414+
399415
it('warns when Field.Label does not render a native label', () => {
400416
const consoleWarn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
401417

‎packages/ui/src/mosaic/components/field/field.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ const Label = React.forwardRef<HTMLLabelElement, FieldLabelProps>(function Mosai
7575
const id = idProp ?? (context ? `cl-field-${generatedId}-label` : undefined);
7676
// A `<label>` activates the control it names, which would open a select; those get a span
7777
// that only focuses it, and are named through `aria-labelledby` instead.
78-
const nativeLabel = context?.labelElementType !== 'span';
78+
const nativeLabel = htmlForProp !== undefined || context?.labelElementType !== 'span';
7979
const controlId = context?.controlId;
8080
const htmlFor = htmlForProp ?? (nativeLabel ? controlId : undefined);
8181
const [label, setLabel] = React.useState<HTMLLabelElement | null>(null);

0 commit comments

Comments
 (0)