Skip to content

Spec.md

Latest commit

 

History

History
135 lines (93 loc) · 4.74 KB

Spec.md

File metadata and controls

135 lines (93 loc) · 4.74 KB

@fluentui/react-label Spec

Background

Labels provide a name or title to a component or group of components, e.g., text fields, checkboxes, radio buttons, and dropdown menus.

Prior Art

Label in Fabric/v8

<Label required>I am a required label</Label>

Props used in v8 Label:

Prop Description
as Element type to render Label as
componentRef Optional callback to access the ILabel interface. Use this instead of ref for accessing the public methods and properties of the component
disabled Renders label as disabled, changing the Label's foreground color
required Renders an asterisk next to the given text
styles Custom styles for the Label
theme Theme provided by HOC

Label in Northstar/v0

<Label content="You have 23 emails" />

Props used in v0 Label:

Prop Description
accessibility Prop to override accessibility behavior
as Element type to render Label as
circular Renders Label with round corners
className Additional CSS class name to apply
color Color for the background of the label
content Label content
fluid Make it so Label takes the width of its container
icon Adds an icon to the label
iconPosition Choose where the icon is placed (Start or End)
image Adds an image to the label
imagePosition Choose where the image is placed (Start or End)
styles Additional custom styles for the component
variables Allows override of theme variables

Conclusion

Moving forward, Label will be a simple component. The converged Label will be based on v8's Label with some minor changes. Most props from v0 will be left out but because of the use of slots, it won't be too difficult to migrate to the converged Label.

Sample Code

The Label component should be simple as shown below. It will just need the text to be rendered. For the required label, it has the option of being a shorthand slot that will allow to customize the label's required text.

<Label>Label</Label>

<Label disabled>Label</Label>

<Label required>Label</Label>

<Label required="**">
  Label
</Label>

<Label icon={<InfoRegular />}>Label</Label>

Variants

  • A Label can be rendered with an asterisk or custom text when is set as required.
  • A Label can render an optional icon slot before its content.

API

See API at Label.types.ts.

Structure

Public

<Label required icon={<InfoRegular />}>
  I'm a Label
</Label>

DOM

<label {/*Label*/} class="...">
  <span {/*icon*/} class="..."><svg>...</svg></span>
  I'm a Label
  <span {/*required*/} class="...">*</span>
</label>

Internal

<slots.root {...slotProps.root}>
  {state.icon && <slots.icon {...slotProps.icon} />}
  {state.children}
  <slots.required {...slotProps.required} />
</slots.root>

Migration

See MIGRATION.md

Behaviors

Component States

Label does not have state attributes.

Interaction

Keyboard, Cursor, Touch, and Screen Readers

  • None

Accessibility

  • Label will use the native label element to render.
  • Label cannot receive focus.
  • Label will have no focusable elements.
  • When a Label is disabled, the required contrast ratio won't be met. This is acceptable behavior due to the nature of the styling. This state should be used sparingly and make it clear that there's no interaction with the control associated with it.