ChipInput

A ChipInput allows users to create chips to filter content or make selections.

Guidelines

When to use chip inputs

The TextInput is utilized to build the ChipInput component, allowing information to be filtered by typing text that is transformed into a chip.

• Create chips by entering letters or words and pressing the Enter key, clicking outside, or tabbing out.
• Edit chips by clicking directly on them and typing.
• Remove chips using its remove button.

Use the ChipInput when users need to simplify a complex filtering process or when they need to edit the filters applied there.

Avoid using ChipInput if the filtering process is simple and doesn't require custom edits. In case you need to select static options that don't require editing, consider using a Checkbox group instead.

Specifications

ChipInputs include the following items:

1. TextInput
   The user can type letters or words within this input to create the chips and filter the information.
2. Chip or chips
   The chip or chips created are stacked next to each other, and they are editable and can be removed.

Component limitations

The base min-width for the ChipInput component is set at @size-1600 (equivalent to 256px in the default Codex theme), but it can be customized to a smaller width if needed. There is no maximum width set.

Chips can vary in length as needed and will expand in width based on text length, with ellipsis applied if text exceeds the available width. Chips may stack into multiple lines within the input when needed.

Refer to the ChipInput component in Codex Figma.

Types

Depending on the placement of the chips, there are two types of ChipInput:

1. Chips within the input field
   In this case, when the chips are created they are placed next to the input’s placeholder text, and they are stacked next to each other.
2. Chips separated from the input field
   In this case, the chips are placed in a light gray box above the input field once they are created.

Interaction states

ChipInput has the following visually separate states:

1. Default
2. Hover on input
3. Focus or active
4. Filled
5. Disabled
6. Hover on chip’s remove button
7. Hover on editable chip
8. Focused editable chip
9. Editing the chip
10. Error default
11. Error hover
12. Error filled

Best practices

Consider the following recommendations when using chip inputs.

Do:

• Use ChipInput to enable users to input multiple items within a single field.

Don't:

• Use ChipInput if only a single item input is anticipated. In this case, consider using alternative components like Select instead.

Keyboard navigation

Key	Function
Tab	It moves the focus between the chips within the input. When the focus is placed on the last chip, it moves the focus to the input to create more chips. While typing in the input, pressing it creates a chip with the typed text and then moves the focus to the next interactive element in tab order.
Shift + Tab	It moves the focus to the previous chip within the input or to the previous interactive element in the page.
Enter	While typing in the input, pressing Enter creates a chip with the typed text and keeps the input focused. If focused on a chip, pressing Enter makes the chip editable.
Esc	While typing in the input, pressing Esc creates a chip with the typed text. Once the chip is created, the input loses focus. When any of the chips or input is focused, pressing Esc removes the focus from the focused element.
backspace	If the focus is placed on a chip, this key removes the chip and moves the focus to the previous chip. If it removes the last chip, it moves the focus to the input. If the cursor is at the start of the input, it moves the focus to the last chip.
Left arrow / Right arrow	Arrow keys navigate between the chips within the input when they are focused.

Demos

Configurable

chip 1

chip 2

Name	Value
Props
separateInput
status	default error
disabled
View
Reading direction	Left to right (LTR) Right to left (RTL)

Basic Usage

Pass an array of chip data to the input using v-model:input-chips. When the user adds or removes a chip, the array will automatically be updated.

chip 1

chip 2

NPM

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
	/>
</template>

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

export default defineComponent( {
	name: 'ChipInputBasic',
	components: {
		CdxChipInput
	},
	setup() {
		const exampleChips = ref( [
			{ value: 'chip 1' },
			{ value: 'chip 2' }
		] );

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

MediaWiki

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
	></cdx-chip-input>
</template>

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

module.exports = defineComponent( {
	name: 'ChipInputBasic',
	components: {
		CdxChipInput
	},
	setup() {
		const exampleChips = ref( [
			{ value: 'chip 1' },
			{ value: 'chip 2' }
		] );

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

With icons

Chips added by the user cannot be added with icons, but icons can be included in chips provided by the parent component.

Camera

Article

NPM

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
	/>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxChipInput } from '@wikimedia/codex';
import { cdxIconCamera, cdxIconArticle } from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'ChipInputWithIcons',
	components: {
		CdxChipInput
	},
	setup() {
		const exampleChips = ref( [
			{ value: 'Camera', icon: cdxIconCamera },
			{ value: 'Article', icon: cdxIconArticle }
		] );

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

MediaWiki

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
	></cdx-chip-input>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxChipInput } = require( '@wikimedia/codex' );
const { cdxIconCamera, cdxIconArticle } = require( './icons.json' );

module.exports = defineComponent( {
	name: 'ChipInputWithIcons',
	components: {
		CdxChipInput
	},
	setup() {
		const exampleChips = ref( [
			{ value: 'Camera', icon: cdxIconCamera },
			{ value: 'Article', icon: cdxIconArticle }
		] );

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

With placeholder

Placeholder and other attributes of the <input> element can be bound to the ChipInput component and will be passed down to the <input> element within.

NPM

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		placeholder="Enter one or more items"
	/>
</template>

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

export default defineComponent( {
	name: 'ChipInputWithPlaceholder',
	components: {
		CdxChipInput
	},
	setup() {
		const exampleChips = ref( [] );

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

MediaWiki

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		placeholder="Enter one or more items"
	></cdx-chip-input>
</template>

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

module.exports = defineComponent( {
	name: 'ChipInputWithPlaceholder',
	components: {
		CdxChipInput
	},
	setup() {
		const exampleChips = ref( [] );

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

Disabled

chip 1

chip 2

NPM

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		:disabled="true"
	/>
</template>

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

export default defineComponent( {
	name: 'ChipInputDisabled',
	components: {
		CdxChipInput
	},
	setup() {
		const exampleChips = ref( [
			{ value: 'chip 1' },
			{ value: 'chip 2' } ]
		);

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

MediaWiki

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		:disabled="true"
	></cdx-chip-input>
</template>

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

module.exports = defineComponent( {
	name: 'ChipInputDisabled',
	components: {
		CdxChipInput
	},
	setup() {
		const exampleChips = ref( [
			{ value: 'chip 1' },
			{ value: 'chip 2' } ]
		);

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

Form field

A ChipInput can be wrapped in the Field component to add features like a semantic label, description and help text, validation messages, and more. See the Field page for more information.

Aliases Alternative names help others easily find the function

NPM

<template>
	<cdx-field>
		<cdx-chip-input
			v-model:input-chips="exampleChips"
		/>
		<template #label>
			Aliases
		</template>
		<template #description>
			Alternative names help others easily find the function
		</template>
	</cdx-field>
</template>

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

export default defineComponent( {
	name: 'ChipInputField',
	components: { CdxChipInput, CdxField },
	setup() {
		const exampleChips = ref( [] );

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

MediaWiki

<template>
	<cdx-field>
		<cdx-chip-input
			v-model:input-chips="exampleChips"
		></cdx-chip-input>
		<template #label>
			Aliases
		</template>
		<template #description>
			Alternative names help others easily find the function
		</template>
	</cdx-field>
</template>

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

module.exports = defineComponent( {
	name: 'ChipInputField',
	components: { CdxChipInput, CdxField },
	setup() {
		const exampleChips = ref( [] );

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

With chip validation

To test chip text before a new chip is added, pass in a validation function via the chipValidator prop. If the chip text fails validation, a new chip will not be added and the "error" status will be set.

If you need access to the current value of the text input, for validation or other purposes, you can use v-model to bind a string ref to the ChipInput, just like you would with a TextInput.

In the example below, the input value is bound with v-model and is used to show the number of remaining characters allowed as the user is typing. A chipValidator is passed in that tests whether the text is 10 or fewer characters.

Aliases Alternative names help others easily find the function

10

NPM

<template>
	<cdx-field
		class="cdx-demo-chip-input-limited"
		:status="status"
		:messages="messages"
	>
		<cdx-chip-input
			v-model:input-chips="exampleChips"
			v-model:input-value="inputValue"
			:chip-validator="chipValidator"
		/>
		<template #label>
			Aliases
		</template>
		<template #description>
			Alternative names help others easily find the function
		</template>
		<template #help-text>
			<span class="cdx-demo-chip-input-limited__char-count" :class="limitClass">
				{{ characterCount }}
			</span>
		</template>
	</cdx-field>
</template>

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

export default defineComponent( {
	name: 'ChipInputWithLimit',
	components: { CdxChipInput, CdxField },
	setup() {
		const inputValue = ref( '' );
		const exampleChips = ref( [] );

		const chipValidator = ( value ) => value.length <= 10;

		const status = computed( () =>
			chipValidator( inputValue.value ) ? 'default' : 'error'
		);
		const messages = { error: 'Chip text is too long' };

		const characterCount = computed( () => 10 - inputValue.value.length );
		const limitClass = computed( () => {
			return {
				'cdx-demo-chip-input-limited__char-count--error': status.value === 'error'
			};
		} );

		return {
			inputValue,
			exampleChips,
			chipValidator,
			status,
			messages,
			characterCount,
			limitClass
		};
	}
} );
</script>

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

.cdx-demo-chip-input-limited {
	&__char-count {
		float: right;

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

MediaWiki

<template>
	<cdx-field
		class="cdx-demo-chip-input-limited"
		:status="status"
		:messages="messages"
	>
		<cdx-chip-input
			v-model:input-chips="exampleChips"
			v-model:input-value="inputValue"
			:chip-validator="chipValidator"
		></cdx-chip-input>
		<template #label>
			Aliases
		</template>
		<template #description>
			Alternative names help others easily find the function
		</template>
		<template #help-text>
			<span class="cdx-demo-chip-input-limited__char-count" :class="limitClass">
				{{ characterCount }}
			</span>
		</template>
	</cdx-field>
</template>

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

module.exports = defineComponent( {
	name: 'ChipInputWithLimit',
	components: { CdxChipInput, CdxField },
	setup() {
		const inputValue = ref( '' );
		const exampleChips = ref( [] );

		const chipValidator = ( value ) => value.length <= 10;

		const status = computed( () =>
			chipValidator( inputValue.value ) ? 'default' : 'error'
		);
		const messages = { error: 'Chip text is too long' };

		const characterCount = computed( () => 10 - inputValue.value.length );
		const limitClass = computed( () => {
			return {
				'cdx-demo-chip-input-limited__char-count--error': status.value === 'error'
			};
		} );

		return {
			inputValue,
			exampleChips,
			chipValidator,
			status,
			messages,
			characterCount,
			limitClass
		};
	}
} );
</script>

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

.cdx-demo-chip-input-limited {
	&__char-count {
		float: right;

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

Vue usage

Attributes passed to input

This component will pass any HTML attributes applied to it, except for CSS class, to the <input> element within the component.

Props

Prop name	Description	Type	Default
inputChips(required)	Current chips present in the input. Provided by v-model binding in the parent component.	ChipInputItem[]
inputValue	Current value of the text input. This prop is optional and should only be used if you need to keep track of the text input value for some reason (e.g. for validation). Optionally provided by v-model:input-value binding in the parent component.	string	null
separateInput	Whether the text input should appear below the set of input chips. By default, the input chips are inline with the input.	boolean	false
status	status attribute of the input.	ValidationStatusType	'default'
chipValidator	Validation function for chip text. If it returns false, the chip will not be added and the error status will be set.	ChipValidator	( value: string ) => true
disabled	Whether the input is disabled.	boolean	false

Events

Event name	Properties	Description
update:input-chips	inputChips ChipInputItem[] - The new set of inputChips	When the input chips change.
update:input-value	inputValue string|number - The new input value	When the input value changes. Only emitted if the inputValue prop is provided.