ChipInput ​

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

Guidelines ​

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

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:

Best practices ​

Consider the following recommendations when using chip inputs.

Keyboard navigation ​

Demos ​

Configurable ​

chipAriaDescription

separateInput

status

disabled

Reading direction

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.

Text for the aria-label of each chip's "remove" button is a required prop.

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		remove-button-label="Remove"
	/>
</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>

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		remove-button-label="Remove"
	></cdx-chip-input>
</template>

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

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

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		remove-button-label="Remove"
	/>
</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>

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		remove-button-label="Remove"
	></cdx-chip-input>
</template>

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

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

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		remove-button-label="Remove"
		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>

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

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

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

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

Disabled ​

<template>
	<cdx-chip-input
		v-model:input-chips="exampleChips"
		remove-button-label="Remove"
		: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>

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

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

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

<template>
	<cdx-field>
		<cdx-chip-input
			v-model:input-chips="exampleChips"
			remove-button-label="remove"
		/>
		<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>

<template>
	<cdx-field>
		<cdx-chip-input
			v-model:input-chips="exampleChips"
			remove-button-label="remove"
		></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' );

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

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

Vue usage ​

Props ​

Events ​