Field

Form field with a label, an input or control, and optional validation handling.

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

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 and error state demo below for more information about how to add and customize an error message.

Label text (optional)Short description text

Longer help text to explain how to use this field

Name	Value
Props
labelIcon
optionalFlag
hideLabel
isFieldset
disabled
status	default error
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

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

NPMMediaWiki

vue

<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>

vue

<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' );

// @vue/component
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 and error state

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 (e.g. a red border in the error state). You do not need to bind the status prop to the child input components.

Setting the status based on field validity is up to you. In the 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.

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

Fieldsets

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. Below are some examples of fieldsets.

Radio group

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

NPMMediaWiki

vue

<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>

vue

<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' );

// @vue/component
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

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

Please enter coordinates as decimal degrees.

Disable entire field

NPMMediaWiki

vue

<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() {
			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;
			}
		}
	}
}
</style>

vue

<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' );

// @vue/component
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() {
			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;
			}
		}
	}
}
</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

NPMMediaWiki

vue

<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-250;

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

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

vue

<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' );

// @vue/component
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-250;

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

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

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

NPMMediaWiki

vue

<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: center;
		flex-direction: row no-wrap;
		justify-content: space-between;

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

vue

<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' );

// @vue/component
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: center;
		flex-direction: row no-wrap;
		justify-content: space-between;

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

Usage

Props

Prop name	Description	Type	Values	Default
`labelIcon`	Icon before the label text. Do not use this if including a start icon within the input component.	`Icon`	-	`''`
`optionalFlag`	Text to indicate that the field is optional. For example, this might be '(optional)' in English. This text will be placed next to the label text.	`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.	`ValidationStatusType`	`'default'`, `'error'`	`'default'`
`messages`	Message text keyed on validation status type.	`ValidationMessages`	-	`() => { return {}; }`

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

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 1Radio 2

With help text

To add help text below the input or control:

Add the .cdx-field__control--has-help-text class to the control wrapper
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

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

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

Error status and message

To display error styles and show an error message:

Add the .cdx-field--status-error class to the outer element
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

Field ​

Demos ​

Configurable ​

With rich description and help text ​

With validation and error state ​

Fieldsets ​

Radio group ​

Complex field with two inputs ​

Fieldset with nested Fields ​

With custom help text content ​

​

Usage ​

Props ​

Slots ​

CSS-only version ​

Markup structure ​

Single input ​

Fieldset ​

With help text ​

Disabled ​

Error status and message ​

Field

Demos

Configurable

With rich description and help text

With validation and error state

Fieldsets

Radio group

Complex field with two inputs

Fieldset with nested Fields

With custom help text content

Usage

Props

Slots

CSS-only version

Markup structure

Single input

Fieldset

With help text

Disabled

Error status and message