Kongponents

Input ​

KInput provides a wrapper around general text inputs, as well as contextual styling and states (error, focus, etc).

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

html
<KInput model-value="This is the input value" placeholder="Placeholder text" />

label ​

String to be used as the input label.

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

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

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

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

html
<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 '_'

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

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

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

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

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

html
<KInput label="Name *" required />

v-model ​

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

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

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

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

html
<KInput label="My tooltip">
  <template #label-tooltip>Id: <code>8576925e-d7e0-4ecd-8f14-15db1765e69a</code></template>
</KInput>

help ​

Content passed in to the help slot will be shown as the help content. The slot content takes precedence over the help prop.

Anything goes here

html
<KInput label="Some label" help="This will be replaced with a slot">
  <template #help>
    Anything goes here
  </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:

html
<KLabel>{{ eventsInput }}</KLabel>
<KInput v-model="eventsInput" @update:modelValue="newValue => eventsInput = newValue" />

char-limit-exceeded ​

html
<KInput @char-limit-exceeded="exampleFunction" />

Fired when the text starts or stops exceeding the limit, returns an object:

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

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

Expose ​

input ​

KInput exposes its internal HTML input element ref via an exposed input property to allow access to the underlying element.

vue
<template>
  <KInput 
    ref="myInput"
    placeholder="Focusable input"
  />
  <KButton
    size="large"
    @click="setFocus"
  >
    Set focus
  </KButton>
</template>

<script setup lang="ts">
const myInputRef = useTemplateRef('myInput')
const setFocus = () => {
  myInputRef.value?.input?.focus()
}
</script>

Released under the Apache-2.0 License.

Copyright © 2019-present Kong, Inc.