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.

Name

Disabled

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

Label

<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

Name

I use the KLabel `info` prop

<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..."/>

showPasswordMaskToggle

When passing type="password", setting showPasswordMaskToggle to true will render an eye icon to the right of input clicking on which allows toggling masking the input value on and off. Defaults to false.

<KInput
  show-password-mask-toggle
  type="password"
/>

WARNING

When this prop is enabled, the icon button takes precedence over any content passed through the after slot.

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.

Name

<KInput label="Name *" required />

v-model

KInput works with v-model for two-way data binding:

test

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

My tooltip

Id: 8576925e-d7e0-4ecd-8f14-15db1765e69a

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

foo bar

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