Input
KInput provides a wrapper around general text inputs, as well as contextual styling and states (error, focus, etc).
<KInput placeholder="Placeholder text" />Props
modelValue
To set the value of the input element without using v-model, you can set the model-value attribute on the input:
<KInput model-value="This is the input value" placeholder="Placeholder text" />label
String to be used as the input label.
<KInput label="Name" placeholder="I'm labelled!" />
<KInput label="Disabled" disabled placeholder="I'm disabled!" />If the label prop is omitted, a label can be implemented with a standalone KLabel. If used separately, the KLabel should be used before KInput and will be styled appropriately.
<KLabel for="my-input">Label</KLabel>
<KInput id="my-input" type="text" placeholder="I have a label" />labelAttributes
Use the labelAttributes prop to configure the KLabel's props if using the label prop. This example shows using the label-attributes to add a tooltip. See the slot section for details on slotting HTML content into the tooltip rather than plain text.
You can add tooltipAttributes to configure the KTooltip's props
<KInput
label="Name"
:label-attributes="{
info: 'I use the KLabel `info` prop',
'data-testid': 'test'
tooltipAttributes: {
maxWidth: '150px'
}
}"
/>help
String to be displayed as help text.
I can help with that.
<KInput help="I can help with that." placeholder="Need help?" />If error is true, the help prop text will be styled as error message.
I can help with that.
<KInput error help="I can help with that." />error
Boolean to indicate whether the element is in an error state and should apply error styling. Defaults to false.
errorMessage
String to be displayed as an error message if error prop is true. This prop will supersede the help prop if both have a value and error is true.
Service name should not contain '_'
<KInput error error-message="Service name should not contain '_'" help="Service name can be anything with only a few exceptions." />characterLimit
Use this prop to specify a character limit for the input. See the @char-limit-exceeded event for more details.
34 / 10
<KInput model-value="This field has too many characters" :character-limit="10" placeholder="Placeholder text" />The character counter will only display below the input if the characterLimit is exceeded.
If the characterLimit is exceeded, the character counter below the KInput will override the display of the provided help and errorMessage text until the character count is within the acceptable range.
TIP
You may also specify a native maxlength attribute on the KInput to limit the number of characters the user is allowed to type in the field. This will prevent the user from exceeding the character limit so the error state will not be shown.
<KInput :character-limit="10" maxlength="10" placeholder="Type..."/>Attribute Binding
You can pass any input attribute and it will get properly bound to the element.
<KInput placeholder="placeholder" />
<KInput type="password" model-value="123" />
<KInput type="number" model-value="1"/>
<KInput type="email" model-value="john.doe@konghq.com"/>
<KInput disabled model-value="disabled"/>
<KInput readonly model-value="read-only"/>
<KInput type="search" model-value="search"/>required
KInput will display a red dot next to the label to indicate a field is required if you set the required attribute and provide a label value. See KLabel's required prop for more information.
NOTE
Text passed in for the label will automatically strip any trailing * when used with the required attribute to prevent duplicate visual indicators for required fields.
<KInput label="Name *" required />v-model
KInput works with v-model for two-way data binding:
<template>
<div class="input-container">
<KInput :label="myInput || 'empty'" v-model="myInput"/>
<KButton @click="clearMyInput">Clear</KButton>
</div>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const myInput = ref<string>('test')
const clearMyInput = (): void => {
myInput.value = ''
}
</script>
<style lang="scss" scoped>
.input-container {
display: flex;
align-items: flex-end;
gap: $kui-space-40;
}
</style>Slots
before and after
Use the before and after slots for inserting icons before and/or after the input field.
<KInput placeholder="Search">
<template #before>
<SearchIcon />
</template>
</KInput>TIP
If you want to make an icon clickable, you must assign role="button" and tabindex="0" attributes to that element and bind an event handler. KBadge will take care of state styling (hover, focus, disabled).
<KInput :model-value="serviceId">
<template #after>
<KClipboardProvider v-slot="{ copyToClipboard }">
<CopyIcon
role="button"
tabindex="0"
@click="() => { copyToClipboard(serviceId) }"
/>
</KClipboardProvider>
</template>
</KInput>KInput takes care of icon color, size and spacing as long as you use icons sourced from @kong/icons package.
TIP
Should you decide to use your own custom icons, you can use design tokens exported by the @kong/design-tokens package to set icon size. The recommended icon size is 20px or kui-icon-size-40.
We also recommend setting the icon style color property to a value of currentColor to utilize default KInput styling for slotted content.
label-tooltip
If you want to utilize HTML in the input label's tooltip, use the slot.
<KInput label="My tooltip">
<template #label-tooltip>Id: <code>8576925e-d7e0-4ecd-8f14-15db1765e69a</code></template>
</KInput>Events
input and update:modelValue
To listen for changes to the KInput value, you can bind to the @input or @update:modelValue events:
<KLabel>{{ eventsInput }}</KLabel>
<KInput v-model="eventsInput" @update:modelValue="newValue => eventsInput = newValue" />char-limit-exceeded
<KInput @char-limit-exceeded="exampleFunction" />Fired when the text starts or stops exceeding the limit, returns an object:
{
value, // current value
length, // length of current value
characterLimit, // character limit
limitExceeded // whether or not the limit has been exceeded
}DOM events
KInput allows you to listen to DOM events:
<KComponent :data="{ myInput: 'hello' }" v-slot="{ data }">
<div>
<KInput
v-model="data.myInput"
@blur="e => (data.myInput = 'blurred')"
@focus="e => (data.myInput = 'focused')"
/>
</div>
</KComponent>