Field

A form field with a label, an input or control, and an optional validation message.

Guidelines

When to use fields

Field provides features for building an accessible, understandable form field to collect user input.

Use the Field component to create form layouts and to create a variety of form inputs, such as text inputs, selects, radio buttons, checkboxes or toggle switches.

If you do not need to collect user input, do not use Field. For example, Field is not necessary to display a search input. Although search is built with a text input component, it triggers an action and is not a form item.

Specifications

It is composed of the following elements:

1. Label
   A label serves as a precise and informative title for the form field, indicating the type of information to be entered. Explore Label to check its different properties.
2. Label’s description (optional)
   An optional description can also be incorporated below the label to provide additional information about it. This description can include plain text, with or without links.
3. Field
   The input element, or a group of inputs, where the user enters information. Field can use any form item such as text input, select, checkbox, etc.
4. Helper text (optional)
   Text that provides supplementary information or instructions to guide users in completing the field correctly. The helper text can include plain text with or without links, and it can also include a number to optionally display the character counter if needed.
5. Validation message
   An inline validation message will appear to provide feedback about the status of the field. For example, to provide an error message to the user when the field contains one or more errors.

Component limitations

Both label and description will wrap onto multiple lines as needed. There are no strict length limits for labels and descriptions, but it's recommended to keep them concise for improved form readability and scanning.

When a fieldset is arranged horizontally, labels stay aligned, with field elements stacked below respecting Field component paddings.

If a Field includes both helper text and a character counter, they will be aligned at the top with a spacing-100 token (equivalent to 16px in the default Codex theme).

Refer to the Field component in Codex Figma.

Types

The Field component's control can be any form item component designed to gather user input, including:

• Text input and text area
• Select
• Combobox
• Checkbox, radio groups, and toggle switch
• Chip input
• Lookup

However, components not intended for collecting user input, such as SearchInput, should not be used within Field.

Interaction states

Form fields have the following visually separate states:

1. Default
2. Interactive state within the field
3. Disabled
4. Error
5. Warning
6. Success

The interactive states will exclusively impact the field item within Field. So hover, focus, filled, and read-only states apply solely to the field item (e.g. the text input).

Best practices

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

Icon

Do:

• Use a start icon next to the label to emphasize the required input in the form field.

Don't:

• Use another icon in the label's section if the field already contains an icon.

Label, description, and helper text

Do:

• Keep the Field’s label short, clear, and easy to scan.
• Use the label’s description for additional information related with the label if needed.
• Use the helper text to provide supplementary guidance on completing the field correctly, including expected input and error prevention.

Don't:

• Make the Field’s label text excessively large, which could make it difficult to scan.
• Include field completion guidelines in the label’s description.
• Place information related to the label below the field. Use the helper text for this purpose instead.

Optional form fields

Do:

• Only indicate the optional Fields in the form.
• Ensure that the entire word "optional" is displayed for translation purposes.

Don't:

• Mark required labels with an asterisk.
• Use abbreviations in the optional indicator.

Label style

Do:

• Include multiple Fields within a fieldset for organization.
• Customize the label of Fields to regular weight when grouped within a fieldset.

Don't:

• Avoid using bold labels in Fields within a fieldset to maintain hierarchy and clarity.

Characters counter

Do:

• Use a character counter only when it's necessary to limit the number of characters in a form input.
• Display an inline error message if the character limit is exceeded.

Don't:

• Use a character counters when the character limit does not need to be communicated to the user.

Content

Form elements should guide the user to fill out the form easily. They will prevent the user from making mistakes.

Label and placeholder

Labels indicate what the input should be. Placeholders act as sample text for the kind of content the user needs to input. Different browsers handle placeholder text differently, and some have trouble displaying translations of placeholders. Use placeholders as helpful additions, but do not rely on them too heavily.

Do:

• Make the label short, clear, and easy to scan. Consistent & Clear
• Provide more context in the placeholder for what's indicated in the label. Clear
• Use examples in the placeholder when expected input formats need to be clarified. Clear

Don't:

• Leave out the label in favor of just a placeholder. Needed & Translatable
• Repeat in the placeholder what’s in the label. Concise

Helper text

Helper text gives a user guidance on how to fill in the form field. These messages often clarify formatting or indicate character restrictions. Giving users appropriate context helps them to quickly and efficiently enter the input without errors.

Do:

• Give clear information about input restrictions. Clear & Accessible

Don't:

• List too many restrictions or use overly technical and robotic language. Relevant

Inline error

These are short, simple contextual messages that allow the user to quickly understand how to fix the error they just made.

Do:

• Let a reader know exactly what to do to fix the issue. Relevant & Trustworthy

Don't:

• State the error without offering a way to correct it. Relevant & Trustworthy

Keyboard navigation

Key	Function
Tab	It moves the focus to the next interactive element in tab order.
Shift + Tab	It moves the focus to the previous interactive element.
Enter	If the focus is placed on one of the interactive elements within the Field, it activates them.

Demos

Configurable

Note that this configurable demo is only shown with a TextInput inside the Field. See the demos below for use of the Field component with other types of inputs or groups of inputs, along with code samples.

See the validation messages demos below for more information about how to add and customize an error message.

Label textShort description text

Longer help text to explain how to use this field

Name	Value
Props
labelIcon
optional
hideLabel
isFieldset
disabled
status	default error warning success
Slots
label
description
help-text
View
Reading direction	Left to right (LTR) Right to left (RTL)
Note: For icon properties, the relevant icon also needs to be imported from the @wikimedia/codex-icons package. See the usage documentation for more information.

With rich description and help text

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

Input type Wikifunctions input type

Choose an option

• boolean
• function
• object
• string

What kind of data does the function accept? See list of input types.

NPM

<template>
	<cdx-field>
		<cdx-select
			v-model:selected="selection"
			:menu-items="menuItems"
			default-label="Choose an option"
		/>

		<template #label>
			Input type
		</template>
		<template #description>
			<a href="https://wikifunctions.beta.wmflabs.org">Wikifunctions</a> input type
		</template>
		<template #help-text>
			What kind of data does the function accept? See <a href="https://wikifunctions.beta.wmflabs.org/wiki/Special:ListZObjectsByType/Z4">list of input types</a>.
		</template>
	</cdx-field>
</template>

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

export default defineComponent( {
	name: 'FieldWithRichText',
	components: {
		CdxField,
		CdxSelect
	},
	setup() {
		const selection = ref( '' );
		const menuItems = [
			{ value: 'boolean' },
			{ value: 'function' },
			{ value: 'object' },
			{ value: 'string' }
		];

		return {
			selection,
			menuItems
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-field>
		<cdx-select
			v-model:selected="selection"
			:menu-items="menuItems"
			default-label="Choose an option"
		></cdx-select>

		<template #label>
			Input type
		</template>
		<template #description>
			<a href="https://wikifunctions.beta.wmflabs.org">Wikifunctions</a> input type
		</template>
		<template #help-text>
			What kind of data does the function accept? See <a href="https://wikifunctions.beta.wmflabs.org/wiki/Special:ListZObjectsByType/Z4">list of input types</a>.
		</template>
	</cdx-field>
</template>

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

module.exports = defineComponent( {
	name: 'FieldWithRichText',
	components: {
		CdxField,
		CdxSelect
	},
	setup() {
		const selection = ref( '' );
		const menuItems = [
			{ value: 'boolean' },
			{ value: 'function' },
			{ value: 'object' },
			{ value: 'string' }
		];

		return {
			selection,
			menuItems
		};
	}
} );
</script>

With validation messages

You can display a validation message based on the current status of the field. Set the status prop based on the field's validity, then pass in an object of messages keyed on validation status type. If there is a message for the current status, it will be displayed.

The status you bind to the Field component will also be passed down to its child components, which will display appropriate styles for that status if they exist (e.g. a red border in the error state). You do not need to bind the status prop to the child input components. Note that form input components currently only have special styles for the error status.

Setting the status based on field validity is up to you. In the error example below, it's done as you're changing the input. You could also validate on blur to give the user a chance to finish filling out the field, as demonstrated in the warning example and the success example.

Error

The error status can be used both to show an error message and to display the error state of the form input. Try entering a username into the field below that's longer than a single character to see the error state and error message.

Username Enter a unique username

Username cannot be longer than 1 character

NPM

<template>
	<cdx-field :status="status" :messages="messages">
		<cdx-text-input v-model="inputValue" />
		<template #label>
			Username
		</template>
		<template #description>
			Enter a unique username
		</template>
		<template #help-text>
			Username cannot be longer than 1 character
		</template>
	</cdx-field>
</template>

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

export default defineComponent( {
	name: 'FieldWithValidation',
	components: {
		CdxField,
		CdxTextInput
	},
	setup() {
		const inputValue = ref( '' );
		const status = computed( () =>
			inputValue.value.length > 1 ? 'error' : 'default'
		);
		const messages = { error: 'Your username is too long' };

		return {
			inputValue,
			status,
			messages
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-field :status="status" :messages="messages">
		<cdx-text-input v-model="inputValue"></cdx-text-input>
		<template #label>
			Username
		</template>
		<template #description>
			Enter a unique username
		</template>
		<template #help-text>
			Username cannot be longer than 1 character
		</template>
	</cdx-field>
</template>

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

module.exports = defineComponent( {
	name: 'FieldWithValidation',
	components: {
		CdxField,
		CdxTextInput
	},
	setup() {
		const inputValue = ref( '' );
		const status = computed( () =>
			inputValue.value.length > 1 ? 'error' : 'default'
		);
		const messages = { error: 'Your username is too long' };

		return {
			inputValue,
			status,
			messages
		};
	}
} );
</script>

Warning

The following example shows a warning message on blur if the username doesn't meet the criteria written in the help text. In this case, the username will be corrected to meet the criteria, and the message informs the user of this change. Note that form inputs do not display a "warning" state.

Username Enter a unique username

Username must be capitalized and have no spaces

NPM

<template>
	<cdx-field :status="status" :messages="messages">
		<cdx-text-input
			v-model="inputValue"
			@input="onInput"
			@blur="validate"
		/>
		<template #label>
			Username
		</template>
		<template #description>
			Enter a unique username
		</template>
		<template #help-text>
			Username must be capitalized and have no spaces
		</template>
	</cdx-field>
</template>

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

export default defineComponent( {
	name: 'FieldWithWarning',
	components: {
		CdxField,
		CdxTextInput
	},
	setup() {
		const inputValue = ref( '' );
		const originalName = ref( '' );
		const status = ref( 'default' );
		const messages = computed( () => {
			return {
				warning: `The username was automatically changed from "${ originalName.value }" to "${ inputValue.value }".`
			};
		} );

		function onInput() {
			// Reset status when input changes.
			status.value = 'default';
		}

		function validate() {
			if ( inputValue.value.length === 0 ) {
				status.value = 'default';
				return;
			}

			// Trim off spaces at the beginning and end; we don't
			// need to inform the user of this.
			inputValue.value = inputValue.value.trim();

			// Store the original username.
			originalName.value = inputValue.value;

			// Remove spaces.
			inputValue.value = inputValue.value.replace( /\s/g, '' );

			// Capitalize.
			inputValue.value = inputValue.value[ 0 ].toUpperCase() + inputValue.value.slice( 1 );

			// Set warning status if the original username
			// was changed.
			status.value = originalName.value === inputValue.value ? 'default' : 'warning';
		}

		return {
			inputValue,
			status,
			messages,
			onInput,
			validate
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-field :status="status" :messages="messages">
		<cdx-text-input
			v-model="inputValue"
			@input="onInput"
			@blur="validate"
		></cdx-text-input>
		<template #label>
			Username
		</template>
		<template #description>
			Enter a unique username
		</template>
		<template #help-text>
			Username must be capitalized and have no spaces
		</template>
	</cdx-field>
</template>

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

module.exports = defineComponent( {
	name: 'FieldWithWarning',
	components: {
		CdxField,
		CdxTextInput
	},
	setup() {
		const inputValue = ref( '' );
		const originalName = ref( '' );
		const status = ref( 'default' );
		const messages = computed( () => {
			return {
				warning: `The username was automatically changed from "${ originalName.value }" to "${ inputValue.value }".`
			};
		} );

		function onInput() {
			// Reset status when input changes.
			status.value = 'default';
		}

		function validate() {
			if ( inputValue.value.length === 0 ) {
				status.value = 'default';
				return;
			}

			// Trim off spaces at the beginning and end; we don't
			// need to inform the user of this.
			inputValue.value = inputValue.value.trim();

			// Store the original username.
			originalName.value = inputValue.value;

			// Remove spaces.
			inputValue.value = inputValue.value.replace( /\s/g, '' );

			// Capitalize.
			inputValue.value = inputValue.value[ 0 ].toUpperCase() + inputValue.value.slice( 1 );

			// Set warning status if the original username
			// was changed.
			status.value = originalName.value === inputValue.value ? 'default' : 'warning';
		}

		return {
			inputValue,
			status,
			messages,
			onInput,
			validate
		};
	}
} );
</script>

Success

The following example shows a success message on blur when the username is unique. Note that form inputs do not display a "success" state.

Username Enter a unique username

NPM

<template>
	<cdx-field :status="status" :messages="messages">
		<cdx-text-input
			v-model="inputValue"
			@input="onInput"
			@blur="validate"
		/>
		<template #label>
			Username
		</template>
		<template #description>
			Enter a unique username
		</template>
	</cdx-field>
</template>

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

export default defineComponent( {
	name: 'FieldWithSuccess',
	components: {
		CdxField,
		CdxTextInput
	},
	setup() {
		const inputValue = ref( '' );
		const status = ref( 'default' );
		const messages = computed( () => {
			return {
				success: `The username "${ inputValue.value }" is available.`
			};
		} );

		function onInput() {
			// Reset status when input changes.
			status.value = 'default';
		}

		function validate() {
			if ( inputValue.value.length === 0 ) {
				status.value = 'default';
				return;
			}

			// If this were real, we'd check to see if the username
			// is actually unique. But this is just an example, so
			// we'll show the success message no matter what.
			status.value = 'success';
		}

		return {
			inputValue,
			status,
			messages,
			onInput,
			validate
		};
	}
} );
</script>

MediaWiki

<template>
	<cdx-field :status="status" :messages="messages">
		<cdx-text-input
			v-model="inputValue"
			@input="onInput"
			@blur="validate"
		></cdx-text-input>
		<template #label>
			Username
		</template>
		<template #description>
			Enter a unique username
		</template>
	</cdx-field>
</template>

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

module.exports = defineComponent( {
	name: 'FieldWithSuccess',
	components: {
		CdxField,
		CdxTextInput
	},
	setup() {
		const inputValue = ref( '' );
		const status = ref( 'default' );
		const messages = computed( () => {
			return {
				success: `The username "${ inputValue.value }" is available.`
			};
		} );

		function onInput() {
			// Reset status when input changes.
			status.value = 'default';
		}

		function validate() {
			if ( inputValue.value.length === 0 ) {
				status.value = 'default';
				return;
			}

			// If this were real, we'd check to see if the username
			// is actually unique. But this is just an example, so
			// we'll show the success message no matter what.
			status.value = 'success';
		}

		return {
			inputValue,
			status,
			messages,
			onInput,
			validate
		};
	}
} );
</script>

Fieldset with radio group

For any field that contains multiple inputs or controls, set the isFieldset prop to true. This will output a <fieldset> element with a <legend> instead of a label.

Groups of Radio or Checkbox components are considered fieldsets.

Notifications Choose how often you'd like to receive notifications

Daily

Weekly

Monthly

Note that you can update this preference later

NPM

<template>
	<cdx-field :is-fieldset="true">
		<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>

		<template #label>
			Notifications
		</template>
		<template #description>
			Choose how often you'd like to receive notifications
		</template>
		<template #help-text>
			Note that you can update this preference later
		</template>
	</cdx-field>
</template>

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

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

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

MediaWiki

<template>
	<cdx-field :is-fieldset="true">
		<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>

		<template #label>
			Notifications
		</template>
		<template #description>
			Choose how often you'd like to receive notifications
		</template>
		<template #help-text>
			Note that you can update this preference later
		</template>
	</cdx-field>
</template>

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

module.exports = defineComponent( {
	name: 'FieldWithRadioGroup',
	components: {
		CdxField,
		CdxRadio
	},
	setup() {
		const radioValue = ref( 'daily' );
		const radios = [
			{
				label: 'Daily',
				value: 'daily'
			},
			{
				label: 'Weekly',
				value: 'weekly'
			},
			{
				label: 'Monthly',
				value: 'monthly'
			}
		];

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

Complex field with two inputs

The field below has two inputs, a TextInput and a Select. In addition to the field-level label, each input needs its own individual label. In this case, the individual labels can be visually hidden. In the example below, the labels are included in two different ways:

• For the TextInput, the Label component is used with hideLabel set to true
• For the Select, an aria-label is applied

To give the user a chance to type a valid coordinate location, this example doesn't validate as the user types, but delays validation until the input is blurred. For an example of how to do validation as the user types, see the validation message demos above.

Note that, when you enter erroneous data in the TextInput below, error styles for both the TextInput and the Select will display since they are both contained in a single Field. If you need to show separate states for each input, see the nested Fields example below.

Coordinate location

Coordinates

to 1/1000 of an arcsecond

• to 1/1000 of an arcsecond
• to 1/100 of an arcsecond
• to 1/10 of an arcsecond
• to an arcsecond

Please enter coordinates as decimal degrees.

Disable entire field

NPM

<template>
	<cdx-field
		class="cdx-demo-complex-field"
		:label-icon="cdxIconMapPin"
		:is-fieldset="true"
		:disabled="disabled"
		:status="status"
		:messages="messages"
	>
		<template #label>
			Coordinate location
		</template>

		<div class="cdx-demo-complex-field__inputs">
			<!-- You can include a visually-hidden label via the Label component... -->
			<cdx-label :visually-hidden="true" input-id="coordinates-value">
				Coordinates
			</cdx-label>
			<cdx-text-input
				id="coordinates-value"
				v-model="coordinatesValue"
				@blur="validate"
			/>

			<!-- ...or just use `aria-label`. -->
			<cdx-select
				v-model:selected="precisionValue"
				aria-label="Precision"
				:menu-items="menuItems"
			/>
		</div>

		<template #help-text>
			Please enter coordinates as decimal degrees.
		</template>
	</cdx-field>

	<cdx-toggle-switch v-model="disabled">
		Disable entire field
	</cdx-toggle-switch>
</template>

<script>
import { defineComponent, ref } from 'vue';
import {
	CdxField,
	CdxLabel,
	CdxSelect,
	CdxTextInput,
	CdxToggleSwitch
} from '@wikimedia/codex';
import { cdxIconMapPin } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'FieldWithTwoInputs',
	components: {
		CdxField,
		CdxLabel,
		CdxSelect,
		CdxTextInput,
		CdxToggleSwitch
	},
	setup() {
		const coordinatesValue = ref( '' );

		const menuItems = [
			{ label: 'to 1/1000 of an arcsecond', value: '.001' },
			{ label: 'to 1/100 of an arcsecond', value: '.01' },
			{ label: 'to 1/10 of an arcsecond', value: '.1' },
			{ label: 'to an arcsecond', value: '1' }
		];
		const precisionValue = ref( '.001' );

		const messages = { error: 'Please enter a valid coordinate location.' };
		const status = ref( 'default' );

		function validate() {
			// eslint-disable-next-line security/detect-unsafe-regex
			const regEx = /^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$/;

			if ( coordinatesValue.value.length === 0 ) {
				status.value = 'default';
				return;
			}

			status.value = regEx.test( coordinatesValue.value ) ? 'default' : 'error';
		}

		const disabled = ref( false );

		return {
			coordinatesValue,
			menuItems,
			precisionValue,
			messages,
			status,
			validate,
			disabled,
			cdxIconMapPin
		};
	}
} );
</script>

<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';

.cdx-demo-complex-field {
	margin-bottom: @spacing-250;

	&__inputs {
		@media screen and ( min-width: @min-width-breakpoint-desktop ) {
			display: flex;
		}

		.cdx-text-input {
			margin-bottom: @spacing-50;

			@media screen and ( min-width: @min-width-breakpoint-desktop ) {
				margin-right: @spacing-50;
				margin-bottom: 0;
			}
		}
	}
}
</style>

MediaWiki

<template>
	<cdx-field
		class="cdx-demo-complex-field"
		:label-icon="cdxIconMapPin"
		:is-fieldset="true"
		:disabled="disabled"
		:status="status"
		:messages="messages"
	>
		<template #label>
			Coordinate location
		</template>

		<div class="cdx-demo-complex-field__inputs">
			<!-- You can include a visually-hidden label via the Label component... -->
			<cdx-label :visually-hidden="true" input-id="coordinates-value">
				Coordinates
			</cdx-label>
			<cdx-text-input
				id="coordinates-value"
				v-model="coordinatesValue"
				@blur="validate"
			></cdx-text-input>

			<!-- ...or just use `aria-label`. -->
			<cdx-select
				v-model:selected="precisionValue"
				aria-label="Precision"
				:menu-items="menuItems"
			></cdx-select>
		</div>

		<template #help-text>
			Please enter coordinates as decimal degrees.
		</template>
	</cdx-field>

	<cdx-toggle-switch v-model="disabled">
		Disable entire field
	</cdx-toggle-switch>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const {
	CdxField,
	CdxLabel,
	CdxSelect,
	CdxTextInput,
	CdxToggleSwitch
} = require( '@wikimedia/codex' );
const { cdxIconMapPin } = require( './icons.json' );

module.exports = defineComponent( {
	name: 'FieldWithTwoInputs',
	components: {
		CdxField,
		CdxLabel,
		CdxSelect,
		CdxTextInput,
		CdxToggleSwitch
	},
	setup() {
		const coordinatesValue = ref( '' );

		const menuItems = [
			{ label: 'to 1/1000 of an arcsecond', value: '.001' },
			{ label: 'to 1/100 of an arcsecond', value: '.01' },
			{ label: 'to 1/10 of an arcsecond', value: '.1' },
			{ label: 'to an arcsecond', value: '1' }
		];
		const precisionValue = ref( '.001' );

		const messages = { error: 'Please enter a valid coordinate location.' };
		const status = ref( 'default' );

		function validate() {
			// eslint-disable-next-line security/detect-unsafe-regex
			const regEx = /^[-+]?([1-8]?\d(\.\d+)?|90(\.0+)?),\s*[-+]?(180(\.0+)?|((1[0-7]\d)|([1-9]?\d))(\.\d+)?)$/;

			if ( coordinatesValue.value.length === 0 ) {
				status.value = 'default';
				return;
			}

			status.value = regEx.test( coordinatesValue.value ) ? 'default' : 'error';
		}

		const disabled = ref( false );

		return {
			coordinatesValue,
			menuItems,
			precisionValue,
			messages,
			status,
			validate,
			disabled,
			cdxIconMapPin
		};
	}
} );
</script>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-demo-complex-field {
	margin-bottom: @spacing-250;

	&__inputs {
		@media screen and ( min-width: @min-width-breakpoint-desktop ) {
			display: flex;
		}

		.cdx-text-input {
			margin-bottom: @spacing-50;

			@media screen and ( min-width: @min-width-breakpoint-desktop ) {
				margin-right: @spacing-50;
				margin-bottom: 0;
			}
		}
	}
}
</style>

Fieldset with nested Fields

In this example, each input within the field needs its own visible label, description, validation status, and validation message. To accomplish this, each input is wrapped in a Field component. The entire field is wrapped in a top-level Field component with isFieldset set to true.

Note that each sub-field has its own status. This enables you to show error styles only for the input that contains the error, not the entire fieldset.

Nested fields will become disabled when their parent field is disabled.

Item weight

Weight value Numerical value of the weight

Unit Must be from pre-approved list of units

Hint: try searching for "grams"

Disable entire field

NPM

<template>
	<cdx-field
		class="cdx-demo-nested-fields"
		:status="fieldsetStatus"
		:messages="fieldsetMessages"
		:is-fieldset="true"
		:disabled="disabled"
	>
		<template #label>
			Item weight
		</template>

		<div class="cdx-demo-nested-fields__inputs">
			<cdx-field
				class="cdx-demo-nested-fields__inputs__weight"
				:status="weightStatus"
				:messages="weightMessages"
			>
				<template #label>
					Weight value
				</template>
				<template #description>
					Numerical value of the weight
				</template>

				<cdx-text-input
					v-model="weightValue"
					@blur="validateWeight"
				/>
			</cdx-field>
			<cdx-field
				class="cdx-demo-nested-fields__inputs__unit"
				:status="unitsStatus"
				:messages="unitsMessages"
			>
				<template #label>
					Unit
				</template>
				<template #description>
					Must be from pre-approved list of units
				</template>
				<template #help-text>
					Hint: try searching for "grams"
				</template>

				<cdx-lookup
					v-model:selected="unitsValue"
					:menu-items="menuItems"
					@input="onLookupInput"
				/>
			</cdx-field>
		</div>
	</cdx-field>
	<cdx-toggle-switch v-model="disabled">
		Disable entire field
	</cdx-toggle-switch>
</template>

<script>
import { defineComponent, ref, computed } from 'vue';
import {
	CdxField,
	CdxLookup,
	CdxTextInput,
	CdxToggleSwitch
} from '@wikimedia/codex';

export default defineComponent( {
	name: 'FieldWithFields',
	components: {
		CdxField,
		CdxLookup,
		CdxTextInput,
		CdxToggleSwitch
	},
	setup() {
		// Set up data for the weight value field.
		const weightValue = ref( '' );
		const weightStatus = ref( 'default' );
		const weightMessages = { error: 'Invalid weight value' };

		function validateWeight() {
			const weightTrimmed = weightValue.value.replace( / /g, '' );
			if ( weightTrimmed.length === 0 ) {
				weightStatus.value = 'default';
				return;
			}
			weightStatus.value = isNaN( Number( weightTrimmed ) ) ?
				'error' : 'default';
		}

		// Set up data for the unit field.
		const unitsValue = ref( '' );
		const unitsStatus = ref( 'default' );
		const unitsMessages = { error: 'No matching units found' };
		const units = [
			{ value: 'ounces' },
			{ value: 'pounds' },
			{ value: 'grams' },
			{ value: 'kilograms' }
		];
		const menuItems = ref( [] );

		/**
		 * Handle lookup input.
		 *
		 * @param {string} value
		 */
		function onLookupInput( value ) {
			if ( value ) {
				menuItems.value = units.filter( ( item ) =>
					item.value.includes( value )
				);
				unitsStatus.value = menuItems.value.length === 0 ? 'error' : 'default';
			} else {
				unitsStatus.value = 'default';
			}
		}

		// Set up data for the wrapper Field component.
		const fieldsetMessages = { error: 'One of the values is invalid.' };
		const fieldsetStatus = computed( () => weightStatus.value === 'error' || unitsStatus.value === 'error' ?
			'error' : 'default'
		);

		const disabled = ref( false );

		return {
			weightValue,
			weightStatus,
			weightMessages,
			validateWeight,
			menuItems,
			onLookupInput,
			unitsValue,
			unitsStatus,
			unitsMessages,
			fieldsetMessages,
			fieldsetStatus,
			disabled
		};
	}
} );
</script>

<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';

.cdx-demo-nested-fields {
	margin-bottom: @spacing-200;

	&__inputs {
		display: flex;
		flex-direction: column;
		gap: @spacing-50;

		@media screen and ( min-width: @min-width-breakpoint-desktop ) {
			flex-direction: row;
		}

		// Disable margin-top on all nested fields.
		.cdx-field {
			margin-top: 0;
		}
	}
}
</style>

MediaWiki

<template>
	<cdx-field
		class="cdx-demo-nested-fields"
		:status="fieldsetStatus"
		:messages="fieldsetMessages"
		:is-fieldset="true"
		:disabled="disabled"
	>
		<template #label>
			Item weight
		</template>

		<div class="cdx-demo-nested-fields__inputs">
			<cdx-field
				class="cdx-demo-nested-fields__inputs__weight"
				:status="weightStatus"
				:messages="weightMessages"
			>
				<template #label>
					Weight value
				</template>
				<template #description>
					Numerical value of the weight
				</template>

				<cdx-text-input
					v-model="weightValue"
					@blur="validateWeight"
				></cdx-text-input>
			</cdx-field>
			<cdx-field
				class="cdx-demo-nested-fields__inputs__unit"
				:status="unitsStatus"
				:messages="unitsMessages"
			>
				<template #label>
					Unit
				</template>
				<template #description>
					Must be from pre-approved list of units
				</template>
				<template #help-text>
					Hint: try searching for "grams"
				</template>

				<cdx-lookup
					v-model:selected="unitsValue"
					:menu-items="menuItems"
					@input="onLookupInput"
				></cdx-lookup>
			</cdx-field>
		</div>
	</cdx-field>
	<cdx-toggle-switch v-model="disabled">
		Disable entire field
	</cdx-toggle-switch>
</template>

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

module.exports = defineComponent( {
	name: 'FieldWithFields',
	components: {
		CdxField,
		CdxLookup,
		CdxTextInput,
		CdxToggleSwitch
	},
	setup() {
		// Set up data for the weight value field.
		const weightValue = ref( '' );
		const weightStatus = ref( 'default' );
		const weightMessages = { error: 'Invalid weight value' };

		function validateWeight() {
			const weightTrimmed = weightValue.value.replace( / /g, '' );
			if ( weightTrimmed.length === 0 ) {
				weightStatus.value = 'default';
				return;
			}
			weightStatus.value = isNaN( Number( weightTrimmed ) ) ?
				'error' : 'default';
		}

		// Set up data for the unit field.
		const unitsValue = ref( '' );
		const unitsStatus = ref( 'default' );
		const unitsMessages = { error: 'No matching units found' };
		const units = [
			{ value: 'ounces' },
			{ value: 'pounds' },
			{ value: 'grams' },
			{ value: 'kilograms' }
		];
		const menuItems = ref( [] );

		/**
		 * Handle lookup input.
		 *
		 * @param {string} value
		 */
		function onLookupInput( value ) {
			if ( value ) {
				menuItems.value = units.filter( ( item ) =>
					item.value.includes( value )
				);
				unitsStatus.value = menuItems.value.length === 0 ? 'error' : 'default';
			} else {
				unitsStatus.value = 'default';
			}
		}

		// Set up data for the wrapper Field component.
		const fieldsetMessages = { error: 'One of the values is invalid.' };
		const fieldsetStatus = computed( () => weightStatus.value === 'error' || unitsStatus.value === 'error' ?
			'error' : 'default'
		);

		const disabled = ref( false );

		return {
			weightValue,
			weightStatus,
			weightMessages,
			validateWeight,
			menuItems,
			onLookupInput,
			unitsValue,
			unitsStatus,
			unitsMessages,
			fieldsetMessages,
			fieldsetStatus,
			disabled
		};
	}
} );
</script>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-demo-nested-fields {
	margin-bottom: @spacing-200;

	&__inputs {
		display: flex;
		flex-direction: column;
		gap: @spacing-50;

		@media screen and ( min-width: @min-width-breakpoint-desktop ) {
			flex-direction: row;
		}

		// Disable margin-top on all nested fields.
		.cdx-field {
			margin-top: 0;
		}
	}
}
</style>

Fieldset with custom help text content

The help-text slot is not limited to static text – more complex markup, including other components and bound values, can be provided here as well. Below is an example of a custom character counter embedded inside a Field. The counter is bound to the modelValue of the TextArea component inside the Field, and an error message is displayed if this text exceeds the maximum allowed number of characters.

Enter your message

Please enter a message of 100 characters or less

100

NPM

<template>
	<cdx-field
		class="cdx-demo-field-with-counter"
		:status="status"
		:messages="errorMessage"
	>
		<template #label>
			Enter your message
		</template>

		<cdx-text-area v-model="userMessageText" />

		<template #help-text>
			<div
				class="cdx-demo-field-with-counter__help-text"
				:class="dynamicClasses"
			>
				<!-- Display help text or error message depending on error status. -->
				<div class="cdx-demo-field-with-counter__help-text__message">
					<p>{{ helpText }}</p>
				</div>

				<!-- Display the remaining character count. -->
				<div class="cdx-demo-field-with-counter__help-text__counter">
					{{ charsRemaining }}
				</div>
			</div>
		</template>
	</cdx-field>
</template>

<script>
import { defineComponent, ref, computed } from 'vue';
import { CdxField, CdxTextArea } from '@wikimedia/codex';

export default defineComponent( {
	name: 'FieldWithCharacterCounter',
	components: {
		CdxField,
		CdxTextArea
	},
	setup() {
		const MAX_MESSAGE_LENGTH = 100;
		const helpText = `Please enter a message of ${ MAX_MESSAGE_LENGTH } characters or less`;

		const errorMessage = { error: 'Message is too long' };
		const userMessageText = ref( '' );

		// This is a simplified example; support for other languages/scripts may
		// require more complex code.
		const charsRemaining = computed( () => MAX_MESSAGE_LENGTH - userMessageText.value.length );
		const status = computed( () => charsRemaining.value < 0 ? 'error' : 'default' );

		const dynamicClasses = computed( () => {
			return {
				'cdx-demo-field-with-counter__help-text--error': status.value === 'error'
			};
		} );

		return {
			userMessageText,
			status,
			charsRemaining,
			errorMessage,
			helpText,
			dynamicClasses
		};
	}
} );
</script>

<style lang="less">
@import ( reference ) '@wikimedia/codex-design-tokens/theme-wikimedia-ui.less';

.cdx-demo-field-with-counter {
	&__help-text {
		display: flex;
		align-items: baseline;
		flex-direction: row no-wrap;
		justify-content: space-between;
		gap: @spacing-100;

		&--error &__counter {
			color: @color-error;
		}
	}
}
</style>

MediaWiki

<template>
	<cdx-field
		class="cdx-demo-field-with-counter"
		:status="status"
		:messages="errorMessage"
	>
		<template #label>
			Enter your message
		</template>

		<cdx-text-area v-model="userMessageText"></cdx-text-area>

		<template #help-text>
			<div
				class="cdx-demo-field-with-counter__help-text"
				:class="dynamicClasses"
			>
				<!-- Display help text or error message depending on error status. -->
				<div class="cdx-demo-field-with-counter__help-text__message">
					<p>{{ helpText }}</p>
				</div>

				<!-- Display the remaining character count. -->
				<div class="cdx-demo-field-with-counter__help-text__counter">
					{{ charsRemaining }}
				</div>
			</div>
		</template>
	</cdx-field>
</template>

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

module.exports = defineComponent( {
	name: 'FieldWithCharacterCounter',
	components: {
		CdxField,
		CdxTextArea
	},
	setup() {
		const MAX_MESSAGE_LENGTH = 100;
		const helpText = `Please enter a message of ${ MAX_MESSAGE_LENGTH } characters or less`;

		const errorMessage = { error: 'Message is too long' };
		const userMessageText = ref( '' );

		// This is a simplified example; support for other languages/scripts may
		// require more complex code.
		const charsRemaining = computed( () => MAX_MESSAGE_LENGTH - userMessageText.value.length );
		const status = computed( () => charsRemaining.value < 0 ? 'error' : 'default' );

		const dynamicClasses = computed( () => {
			return {
				'cdx-demo-field-with-counter__help-text--error': status.value === 'error'
			};
		} );

		return {
			userMessageText,
			status,
			charsRemaining,
			errorMessage,
			helpText,
			dynamicClasses
		};
	}
} );
</script>

<style lang="less">
@import 'mediawiki.skin.variables.less';

.cdx-demo-field-with-counter {
	&__help-text {
		display: flex;
		align-items: baseline;
		flex-direction: row no-wrap;
		justify-content: space-between;
		gap: @spacing-100;

		&--error &__counter {
			color: @color-error;
		}
	}
}
</style>

Vue usage

This component can wrap the following:

• A single form input or control
• An input group (e.g. a group of Radios or Checkboxes)
• A set of nested fields (inputs wrapped in their own Field components).

The following Codex components can be used inside the Field component:

• Checkbox
• ChipInput
• Combobox
• Lookup
• Radio
• SearchInput
• Select
• TextArea
• TextInput
• ToggleSwitch

Props

Prop name	Description	Type	Default
labelIcon	Icon before the label text. Do not use this if including a start icon within the input component.	Icon	''
optional	Whether the field is optional. This will add a flag next to the label indicating that the field is optional.	boolean	false
optionalFlag	Text to indicate that the field is optional. Omit this prop to use the default value, "(optional)".	string	''
hideLabel	Whether the label should be visually hidden. Note that this will also hide the description.	boolean	false
isFieldset	Whether this field contains a group of inputs. When true, this outputs a <fieldset> element with a semantic <legend>. When false, it outputs a <div> with a semantic <label>.	boolean	false
disabled	Whether the entire field is disabled.	boolean	false
status	status attribute of the input. This also determines which validation message is shown.	ValidationStatusType	'default'
messages	Message text keyed on validation status type.	ValidationMessages	{}

Slots

Name	Description	Bindings
label	Label text.
description	Short description text.
default	Input, control, or input group.
help-text	Further explanation of how to use this field.

CSS-only version

See the CSS-only Label docs for instructions on making the label visually-hidden or adding a label icon.

Markup structure

Single input

Label text (optional) Short description text

<!-- Outer element is a <div>. -->
<div class="cdx-field">
  <!-- Label. -->
  <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/control wrapper. -->
  <div class="cdx-field__control">
    <!-- Input or control. -->
    <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>
  </div>
</div>

Fieldset

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

When outputting a <fieldset>, the markup of this component is quite different:

• The outer element is the <fieldset> instead of a <div>
• A <legend> is used instead of a <label>. See docs on the CSS-only Label for more info.
• The description is included inside the <legend>
• The for and aria-describedby attributes are not needed

Legend text (optional) Short description text

Radio 1

Radio 2

<!-- Outer element is the <fieldset>. -->
<fieldset class="cdx-field">
  <!-- Legend. -->
  <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>
  <!-- Input/control wrapper. -->
  <div class="cdx-field__control">
    <div 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>
    </div>
    <div 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>
    </div>
  </div>
</fieldset>

With help text

To add help text below the input or control, add a <div> below the control wrapper with the class cdx-field__help-text

This works with single fields and fieldsets.

Input typeWikifunctions input type

Choose an optionbooleanfunctionobjectstring

What kind of data does the function accept? See list of input types.

<div class="cdx-field">
  <div class="cdx-label">
    <label class="cdx-label__label" for="cdx-demo-input-2">
      <span class="cdx-label__label__text">Input type</span>
    </label>
    <span id="cdx-demo-description-2" class="cdx-label__description">
      <a
        href="https://wikifunctions.beta.wmflabs.org/wiki/Wikifunctions:Main_Page"
        >Wikifunctions</a
      >
      input type
    </span>
  </div>
  <div class="cdx-field__control">
    <select class="cdx-select">
      <option value="">Choose an option</option>
      <option value="boolean">boolean</option>
      <option value="function">function</option>
      <option value="object">object</option>
      <option value="string">string</option>
    </select>
  </div>
  <div class="cdx-field__help-text">
    What kind of data does the function accept? See
    <a
      href="https://wikifunctions.beta.wmflabs.org/wiki/Special:ListObjectsByType/Z4"
      >list of input types</a
    >.
  </div>
</div>

Disabled

To display a disabled field:

• Add the .cdx-field--disabled class to the outer element
• Add the .cdx-label--disabled class to the .cdx-label element
• Disable the input(s) or control(s) (in the example below, the disabled attribute is added to the <input> element)

This works with single fields and fieldsets.

Label text

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

Error status and message

To display error styles and show an error message:

• Apply error styles to the input (in the example below, the .cdx-text-input--status-error class is applied to the text input wrapper)
• Add the validation message below the control wrapper

Label text

Error message text

<div class="cdx-field">
  <div class="cdx-label">
    <label class="cdx-label__label" for="cdx-demo-input-3">
      <span class="cdx-label__label__text">Label text</span>
    </label>
  </div>
  <div class="cdx-field__control">
    <div class="cdx-text-input cdx-text-input--status-error">
      <input id="cdx-demo-input-3" class="cdx-text-input__input" type="text" />
    </div>
  </div>
  <div class="cdx-field__validation-message">
    <div
      class="cdx-message cdx-message--inline cdx-message--error"
      role="alert"
    >
      <span class="cdx-message__icon"></span>
      <div class="cdx-message__content">Error message text</div>
    </div>
  </div>
</div>