Label ​

A Label provides a descriptive title for a form input. Having labels is essential when filling out a form, since each field is associated with its label.

Guidelines ​

Using labels ​

The Label component will be placed above each form Field. An optional indicator, a tooltip, and a description could also be included next to the label text.

Specifications ​

Label is used within Field. It can also be used on its own for cases when the Field component cannot or should not be used (e.g. to label a SearchInput). The Label may include the following elements:

1. Icon (optional)
   A start icon can be included to visually enhance the label's context. This icon is fully customizable and any icon from the provided list can be used. Use a simple icon that is easily comprehensible to users.
2. Label text
   A clear and descriptive title for the form field that tells the user what information to enter.
3. Field indicator (optional)
   Subtle text indicating that the field associated with the label is not required.
4. Description (optional)
   Subtle descriptive text that provides additional information about the field.

The Label will be bold by default. However, it can be customized to regular weight when needed in specific cases:

• Bold labels should be used when grouping two or more form fields under a title with a larger text size.
• Regular labels should be used when grouped under a title with the same text size as the form field label. This prevents hierarchy issues and ensures consistency.

Label and description can wrap onto multiple lines as needed, without strict length limits. However, it's best to keep them concise for better form readability. If the label spans multiple lines, the optional indicator will appear next to the last line of the label.

Refer to the Label component in Codex Figma.

Interaction states ​

Label includes only two states:

1. Default
2. Disabled

Best practices ​

Consider the following recommendations when using labels within form fields. For more detailed information about form fields, consult the guidelines for constructing forms.

Usage ​

Icon ​

Label and description ​

Optional fields ​

Label style ​

Keyboard navigation ​

Demos ​

Configurable ​

<cdx-label optional-flag="(optional)">Label text
<template #description>Short description text</template></cdx-label>

icon

optionalFlag

visuallyHidden

isLegend

disabled

default

description

Reading direction

Basic usage ​

When using the Label component with an input, make sure to add an id attribute to the input and use that to set the for attribute on the label. These attributes will be applied on the proper element within each component (in the example below, that's the <label> for the Label component, and the <input> for the TextInput).

<template>
	<div>
		<cdx-label input-id="username-input">
			Username
		</cdx-label>
		<cdx-text-input id="username-input" v-model="inputValue" />
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextInput, CdxLabel } from '@wikimedia/codex';

export default defineComponent( {
	name: 'LabelBasic',
	components: { CdxTextInput, CdxLabel },
	setup() {
		const inputValue = ref( '' );

		return {
			inputValue
		};
	}
} );
</script>

<template>
	<div>
		<cdx-label input-id="username-input">
			Username
		</cdx-label>
		<cdx-text-input id="username-input" v-model="inputValue"></cdx-text-input>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextInput, CdxLabel } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'LabelBasic',
	components: { CdxTextInput, CdxLabel },
	setup() {
		const inputValue = ref( '' );

		return {
			inputValue
		};
	}
} );
</script>

Visually-hidden label ​

In rare instances, you may not need a visible label if it's very clear from context how to use an input. To achieve this, you can use the Label component to create a semantic label for assistive technology, but add the visuallyHidden prop to visually hide the label.

Note that this will hide the entire output of the component, including the description.

<template>
	<div>
		<cdx-label input-id="sort-order-select" :visually-hidden="true">
			Sort results
		</cdx-label>
		<cdx-select
			id="sort-order-select"
			v-model:selected="selection"
			:menu-items="menuItems"
		/>
	</div>
</template>

<script>
import { defineComponent } from 'vue';
import { CdxSelect, CdxLabel } from '@wikimedia/codex';
export default defineComponent( {
	name: 'LabelVisuallyHidden',
	components: { CdxSelect, CdxLabel },
	data() {
		return {
			menuItems: [
				{ label: 'Sort by: latest', value: 'recency' },
				{ label: 'Sort by: alphabetical', value: 'alphabetical' }
			],
			selection: 'recency'
		};
	}
} );
</script>

<template>
	<div>
		<cdx-label input-id="sort-order-select" :visually-hidden="true">
			Sort results
		</cdx-label>
		<cdx-select
			id="sort-order-select"
			v-model:selected="selection"
			:menu-items="menuItems"
		></cdx-select>
	</div>
</template>

<script>
const { defineComponent } = require( 'vue' );
const { CdxSelect, CdxLabel } = require( '@wikimedia/codex' );
// @vue/component
module.exports = defineComponent( {
	name: 'LabelVisuallyHidden',
	components: { CdxSelect, CdxLabel },
	data() {
		return {
			menuItems: [
				{ label: 'Sort by: latest', value: 'recency' },
				{ label: 'Sort by: alphabetical', value: 'alphabetical' }
			],
			selection: 'recency'
		};
	}
} );
</script>

With rich description text ​

You can include markup in the description slot. Only links and text formatting are recommended as description text should be concise.

<template>
	<div>
		<cdx-label input-id="muted-users-input">
			Muted users
			<template #description>
				Do not display notifications from these users.
				<a href="https://www.mediawiki.org/wiki/Help:Notifications#mute">Learn more about how this works</a>.
			</template>
		</cdx-label>
		<cdx-text-input
			id="muted-users-input"
			v-model="inputValue"
			placeholder="Add users..."
		/>
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextInput, CdxLabel } from '@wikimedia/codex';

export default defineComponent( {
	name: 'LabelWithRichText',
	components: { CdxTextInput, CdxLabel },
	setup() {
		const inputValue = ref( '' );

		return {
			inputValue
		};
	}
} );
</script>

<template>
	<div>
		<cdx-label input-id="muted-users-input">
			Muted users
			<template #description>
				Do not display notifications from these users.
				<a href="https://www.mediawiki.org/wiki/Help:Notifications#mute">Learn more about how this works</a>.
			</template>
		</cdx-label>
		<cdx-text-input
			id="muted-users-input"
			v-model="inputValue"
			placeholder="Add users..."
		></cdx-text-input>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextInput, CdxLabel } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'LabelWithRichText',
	components: { CdxTextInput, CdxLabel },
	setup() {
		const inputValue = ref( '' );

		return {
			inputValue
		};
	}
} );
</script>

Label vs. legend ​

This component outputs a <label> element by default. When the isLegend prop is set to true, it will instead output a <legend> element. Use this within a <fieldset> element.

There is a named slot in the Label component, description, for including more information about the field. It's important to note that, when isLegend is true, the description will be rendered inside the <legend> element to ensure it will be read by assistive technology.

Below are examples of a label and a legend with an associated description.

<template>
	<div>
		<cdx-label input-id="name-input">
			Name
			<template #description>
				Enter your preferred name
			</template>
		</cdx-label>
		<cdx-text-input id="name-input" v-model="inputValue" />
	</div>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxTextInput, CdxLabel } from '@wikimedia/codex';

export default defineComponent( {
	name: 'LabelWithDescription',
	components: { CdxTextInput, CdxLabel },
	setup() {
		const inputValue = ref( '' );

		return {
			inputValue
		};
	}
} );
</script>

<template>
	<div>
		<cdx-label input-id="name-input">
			Name
			<template #description>
				Enter your preferred name
			</template>
		</cdx-label>
		<cdx-text-input id="name-input" v-model="inputValue"></cdx-text-input>
	</div>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxTextInput, CdxLabel } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'LabelWithDescription',
	components: { CdxTextInput, CdxLabel },
	setup() {
		const inputValue = ref( '' );

		return {
			inputValue
		};
	}
} );
</script>

<template>
	<fieldset class="cdx-demo-legend">
		<cdx-label :is-legend="true">
			Notifications
			<template #description>
				Choose how often you'd like to receive notifications
			</template>
		</cdx-label>
		<cdx-radio
			v-for="radio in radios"
			:key="'radio-' + radio.value"
			v-model="radioValue"
			name="radio-group"
			:input-value="radio.value"
		>
			{{ radio.label }}
		</cdx-radio>
	</fieldset>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxRadio, CdxLabel } from '@wikimedia/codex';

export default defineComponent( {
	name: 'LegendWithDescription',
	components: { CdxRadio, CdxLabel },
	setup() {
		const radioValue = ref( 'daily' );
		const radios = [
			{
				label: 'Daily',
				value: 'daily'
			},
			{
				label: 'Weekly',
				value: 'weekly'
			},
			{
				label: 'Monthly',
				value: 'monthly'
			}
		];

		return {
			radioValue,
			radios
		};
	}
} );
</script>

<style lang="less">
.cdx-demo-legend {
	// Remove <fieldset> border and padding.
	border: 0;
	padding: 0;
}
</style>

<template>
	<fieldset class="cdx-demo-legend">
		<cdx-label :is-legend="true">
			Notifications
			<template #description>
				Choose how often you'd like to receive notifications
			</template>
		</cdx-label>
		<cdx-radio
			v-for="radio in radios"
			:key="'radio-' + radio.value"
			v-model="radioValue"
			name="radio-group"
			:input-value="radio.value"
		>
			{{ radio.label }}
		</cdx-radio>
	</fieldset>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxRadio, CdxLabel } = require( '@wikimedia/codex' );

// @vue/component
module.exports = defineComponent( {
	name: 'LegendWithDescription',
	components: { CdxRadio, CdxLabel },
	setup() {
		const radioValue = ref( 'daily' );
		const radios = [
			{
				label: 'Daily',
				value: 'daily'
			},
			{
				label: 'Weekly',
				value: 'weekly'
			},
			{
				label: 'Monthly',
				value: 'monthly'
			}
		];

		return {
			radioValue,
			radios
		};
	}
} );
</script>

<style lang="less">
.cdx-demo-legend {
	// Remove <fieldset> border and padding.
	border: 0;
	padding: 0;
}
</style>

Vue usage ​

Props ​

Slots ​

CSS-only version ​

Markup structure ​

Examples are shown with inputs to demonstrate the ARIA attributes required to connect the label and input.

Label ​

Use a <label> element for a single input.

<!-- Outer element is a <div>. -->
<div class="cdx-label">
  <!-- Label element. Include a `for` attribute to connect it with an input. -->
  <label class="cdx-label__label" for="cdx-demo-input-1">
    <!-- Label text. -->
    <span class="cdx-label__label__text">Label text</span>
    <!-- Optional flag. -->
    <span class="cdx-label__label__optional-flag"> (optional)</span>
  </label>
  <!-- Description. Include an `id` attribute so the input can have an
	`aria-describedby` attribute. -->
  <span id="cdx-demo-description-1" class="cdx-label__description">
    Short description text
  </span>
</div>
<!-- Input for demo purposes. -->
<div class="cdx-text-input">
  <!-- Has `id` and `aria-describedby` attributes. -->
  <input
    id="cdx-demo-input-1"
    class="cdx-text-input__input"
    type="text"
    aria-describedby="cdx-demo-description-1"
  />
</div>

Legend ​

Inside a <form>, use a <legend> element within a <fieldset> for input groups.

When outputting a <legend> rather than a <label>, the markup of this component is quite different:

• There is no wrapper <div>—<legend> must be a direct child of <fieldset>
• The description is included inside the <legend>
• The for and aria-describedby attributes are not needed

<!-- Note that the `cdx-field` class will remove browser fieldset styles. -->
<fieldset class="cdx-field">
  <!-- Outer element is the <legend> element. -->
  <legend class="cdx-label">
    <!-- Wrapper span for the first line of text (legend text + optional flag). -->
    <span class="cdx-label__label">
      <!-- Legend text. -->
      <span class="cdx-label__label__text">Legend text</span>
      <!-- Optional flag. -->
      <span class="cdx-label__label__optional-flag"> (optional)</span>
    </span>
    <!-- Description text, which must be included inside the <legend> element. -->
    <span class="cdx-label__description"> Short description text </span>
  </legend>
  <!-- Radio group for demo purposes. -->
  <div>
    <span class="cdx-radio">
      <input
        id="cdx-docs-radio-1"
        class="cdx-radio__input"
        type="radio"
        name="radio-legend-demo"
        checked
      />
      <span class="cdx-radio__icon"></span>
      <label class="cdx-radio__label" for="cdx-docs-radio-1">Radio 1</label>
    </span>
    <span class="cdx-radio">
      <input
        id="cdx-docs-radio-2"
        class="cdx-radio__input"
        type="radio"
        name="radio-legend-demo"
      />
      <span class="cdx-radio__icon"></span>
      <label class="cdx-radio__label" for="cdx-docs-radio-2">Radio 2</label>
    </span>
  </div>
</fieldset>

With icon ​

To add an icon to the label:

• Add an empty <span> before the label text with the classes .cdx-label__label__icon and a custom class that you can target to add the CSS-only icon
• Apply the CSS-only icon mixin to that <span>

This works for <label> and <legend>.

<div class="cdx-label">
  <label class="cdx-label__label" for="cdx-demo-input-2">
    <span class="cdx-label__label__icon cdx-demo-css-icon--wiki-text"></span>
    <span class="cdx-label__label__text">Signature</span>
  </label>
  <span id="cdx-demo-description-2" class="cdx-label__description">
    Enter your signature using plain text or wikitext
  </span>
</div>
<div class="cdx-text-input">
  <input
    id="cdx-demo-input-2"
    class="cdx-text-input__input"
    type="text"
    aria-describedby="cdx-demo-description-2"
  />
</div>

// Note: you must import the design tokens before importing the css-icon mixin
@import (reference) "@wikimedia/codex-design-tokens/theme-wikimedia-ui.less";
@import (reference) "@wikimedia/codex/mixins/css-icon.less";

.cdx-demo-css-icon--wiki-text {
  .cdx-mixin-css-icon( @cdx-icon-wiki-text );
}

@import "mediawiki.skin.variables.less";

.cdx-demo-css-icon--wiki-text {
  .cdx-mixin-css-icon( @cdx-icon-wiki-text );
}

Visually hidden ​

Occasionally, there may be a use case for the label to be visually hidden. In these cases, it should still be present in the DOM with appropriate elements and ARIA attributes.

To visually hide the label, add the .cdx-label--visually-hidden class to the outer element. This works for <label> and <legend>.

<div class="cdx-label cdx-label--visually-hidden">
  <label class="cdx-label__label" for="cdx-demo-input-3">
    <span class="cdx-label__label__text">Field with invisible label</span>
  </label>
</div>
<div class="cdx-text-input">
  <input
    id="cdx-demo-input-3"
    class="cdx-text-input__input"
    type="text"
    placeholder="Do not actually use placeholders as labels!"
  />
</div>

Disabled ​

Add the .cdx-label--disabled class to the outer element to get disabled styles. This works for <label> and <legend>.

<div class="cdx-label cdx-label--disabled">
  <label class="cdx-label__label" for="cdx-demo-input-4">
    <span class="cdx-label__label__text">Label text </span>
  </label>
</div>
<div class="cdx-text-input">
  <input
    id="cdx-demo-input-4"
    class="cdx-text-input__input"
    type="text"
    disabled
  />
</div>