---
title: "MazInput"
description: "MazInput is a standalone component that replaces the standard html input text with a beautiful design system. Many options like colors, sizes, disabled, loading, error, warning, valid states, error messages and icons are included."
package: "maz-ui"
url: "https://maz-ui.com/components/maz-input"
---

# MazInput

> MazInput is a standalone component that replaces the standard html input text with a beautiful design system. Many options like colors, sizes, disabled, loading, error, warning, valid states, error messages and icons are included.

- Package: `maz-ui`
- Import: `import MazInput from 'maz-ui/components/MazInput'`
- Nuxt: auto-imported by `@maz-ui/nuxt`, no import needed in a Nuxt app
- Web: https://maz-ui.com/components/maz-input

> Before use it, you should install the MazUi plugin in your project, follow instructions in [Getting Started](../guide/getting-started.md)

## Basic usage

```vue
<script setup>
import MazInput from 'maz-ui/components/MazInput'
import { ref } from 'vue'

const inputValue = ref()
</script>

<template>
  <MazInput
    v-model="inputValue"
    label="Label"
    autocomplete="off"
  />
</template>
```

## Top label

```html
<MazInput v-model="inputValue" top-label="Top label" placeholder="Placeholder" />
```

## Assistive text

```html
<MazInput v-model="inputValue" top-label="Top label" assistive-text="Assistive text" placeholder="Placeholder" />
```

## Password

```html
<MazInput v-model="passwordValue" label="Label" type="password" />
```

## Placeholder

```html
<MazInput v-model="inputValue" placeholder="placeholder" />
```

## Required

```html
<MazInput v-model="inputValue" label="label required" required />
```

## Disabled

```html
<MazInput v-model="inputValue" label="label disabled" disabled />
```

## Hint

> Will replace the label, useful to display short message

```html
<MazInput v-model="defaultInputValue" label="label hint" hint="An error occured" error />
```

## Icons

### Use icon name

**Details: View code**

When you use the properties `end-icon`, `start-icon` or `icon` with the icon name (string), the component uses `<MazIcon icon="..." />` component.

Check out how [MazIcon](./maz-icon.md) works, see all available icons and download them to put them in your public folder.

```html
<MazInput v-model="inputValue" label="label icons" start-icon="/banknotes.svg" end-icon="/user.svg" />
```

### Use your own SVG icons

**Details: View code**

```html
<MazInput v-model="inputValue" label="label icons">
  <template #start-icon>
    <svg width="1em" height="1em" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path
        d="M2.25 18.75C7.71719 18.75 13.0136 19.4812 18.0468 20.8512C18.7738 21.0491 19.5 20.5086 19.5 19.7551V18.75M3.75 4.5V5.25C3.75 5.66421 3.41421 6 3 6H2.25M2.25 6V5.625C2.25 5.00368 2.75368 4.5 3.375 4.5H20.25M2.25 6V15M20.25 4.5V5.25C20.25 5.66421 20.5858 6 21 6H21.75M20.25 4.5H20.625C21.2463 4.5 21.75 5.00368 21.75 5.625V15.375C21.75 15.9963 21.2463 16.5 20.625 16.5H20.25M21.75 15H21C20.5858 15 20.25 15.3358 20.25 15.75V16.5M20.25 16.5H3.75M3.75 16.5H3.375C2.75368 16.5 2.25 15.9963 2.25 15.375V15M3.75 16.5V15.75C3.75 15.3358 3.41421 15 3 15H2.25M15 10.5C15 12.1569 13.6569 13.5 12 13.5C10.3431 13.5 9 12.1569 9 10.5C9 8.84315 10.3431 7.5 12 7.5C13.6569 7.5 15 8.84315 15 10.5ZM18 10.5H18.0075V10.5075H18V10.5ZM6 10.5H6.0075V10.5075H6V10.5Z"
        stroke="currentColor"
        stroke-width="1.5"
        stroke-linecap="round"
        stroke-linejoin="round"
      />
    </svg>
  </template>
  <template #end-icon>
    <svg width="1em" height="1em" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
      <path
        d="M15.75 6C15.75 8.07107 14.071 9.75 12 9.75C9.9289 9.75 8.24996 8.07107 8.24996 6C8.24996 3.92893 9.9289 2.25 12 2.25C14.071 2.25 15.75 3.92893 15.75 6Z"
        stroke="currentColor"
        stroke-width="1.5"
        stroke-linecap="round"
        stroke-linejoin="round"
      />
      <path
        d="M4.5011 20.1182C4.5714 16.0369 7.90184 12.75 12 12.75C16.0982 12.75 19.4287 16.0371 19.4988 20.1185C17.216 21.166 14.6764 21.75 12.0003 21.75C9.32396 21.75 6.78406 21.1659 4.5011 20.1182Z"
        stroke="currentColor"
        stroke-width="1.5"
        stroke-linecap="round"
        stroke-linejoin="round"
      />
    </svg>
  </template>
</MazInput>
```

### Use [vite-svg-loader](https://github.com/jpkleemans/vite-svg-loader)

**Details: View code**

```vue
<script lang="ts" setup>
import MazBanknotes from '@maz-ui/svg/banknotes.svg'
import MazUser from '@maz-ui/svg/user.svg'
import MazInput from 'maz-ui/components/MazInput'
import { ref } from 'vue'

const inputValue = ref('value')
</script>

<template>
  <MazInput
    v-model="inputValue"
    label="label icons"
    :start-icon="MazBanknotes"
    :end-icon="MazUser"
  />
</template>
```

### Pass a full `MazIconProps` object

`startIcon` and `endIcon` also accept a full `MazIconProps` object - pass the same shape `<MazIcon>` accepts to override the size, set a `<title>` for screen readers, attach `svgAttributes`, etc.

**Details: View code**

```vue
<script lang="ts" setup>
import MazInput from 'maz-ui/components/MazInput'
import { MazBanknotes } from '@maz-ui/icons/raw/MazBanknotes'
import { ref } from 'vue'

const inputValue = ref('value')
</script>

<template>
  <MazInput
    v-model="inputValue"
    label="amount"
    :start-icon="{
      icon: MazBanknotes,
      size: 'lg',
      title: 'Amount in USD',
    }"
  />
</template>
```

## Auto focus

> Will focus automatically the component

```html
<MazInput v-model="inputValue" label="label auto-focus" auto-focus />
```

## Debounce

> The value emit by the input will be delayed, usefull for searching
>
> The attribute `debounce` is in milliseconds
>
> If the debounce is true, the default debounce delay is 500ms

```html
<MazInput v-model="inputValue" label="label debounce" :debounce="1000" />
```

## Sizes

> Use the attribute `size` with a value in

```vue
<script setup lang="ts">
const sizes = ['mini', 'xs', 'sm', 'md', 'lg', 'xl']
</script>

<template>
  <MazInput
    v-for="size in sizes"
    :key="size"
    v-model="inputValue"
    :label="size"
    :size="size"
  />
</template>
```

**Note: Zoom on iOS**

iOS zooms the page when a focused field has a font size below `16px` (most sizes with a `14px` `base-font-size`). This applies to every form field: `MazInput` and the components built on it, `MazTextarea`, `MazInputCode`... To prevent it without changing the design of the fields, enable the `general.preventIosInputZoom` option of [@maz-ui/nuxt](../ecosystem/nuxt.md), or call [preventIosInputZoom](../ecosystem/utils/prevent-ios-input-zoom.md) from `@maz-ui/utils` in a Vue app.

## Colors

**Tip:**

Click on each input to show colors

```vue
<script setup>
const colors = ['primary', 'secondary', 'info', 'success', 'warning', 'destructive', 'accent', 'contrast']
</script>

<template>
  <MazInput
    v-for="name in colors"
    :key="name"
    v-model="inputValue"
    :label="name"
    :color="name"
  />
</template>
```

## Rounded Size

Use the attribute `rounded-size` with a value in `'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'`

```html
<MazInput rounded-size="none" placeholder="Rounded input" />
<MazInput rounded-size="sm" placeholder="Rounded input" />
<MazInput rounded-size="md" placeholder="Rounded input" />
<MazInput rounded-size="lg" placeholder="Rounded input" />
<MazInput rounded-size="xl" placeholder="Rounded input" />
<MazInput rounded-size="full" placeholder="Rounded input" />
```

## State

**destructive**

```html
<MazInput v-model="inputValue" label="Label" error />
```

**Warning**

```html
<MazInput v-model="inputValue" label="Label" warning />
```

**Success**

```html
<MazInput v-model="inputValue" label="Label" success />
```

## MazInput API

`import MazInput from 'maz-ui/components/MazInput'`

### Props

- `model-value` (`T`, `v-model`): The current value of the input field. This prop is used for two-way data binding with v-model.
- `placeholder` (`string`): Text displayed when the input is empty to guide the user.
- `label` (`string`): Floating label that appears inside the input and moves up when focused or filled. Provides better UX than traditional placeholders.
- `top-label` (`string`): Static label displayed above the input field. Unlike the floating label, this remains fixed.
- `assistive-text` (`string`): Helper text displayed below the input to provide additional context or validation feedback.
- `color` (`"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"`, default: `"primary"`): Theme color that affects the border and focus states of the input.
- `type` (`InputTypeHTMLAttribute`, default: `"text"`): HTML input type attribute that determines the input behavior and validation. Values: `'text'`, `'password'`, `'email'`, `'number'`, `'tel'`, `'url'`, `'search'`, `'date'`, `'time'`, `'datetime-local'`, `'month'`, `'week'` (non exhaustive).
- `required` (`boolean`, default: `false`): Makes the input field mandatory for form submission.
- `disabled` (`boolean`, default: `false`): Disables the input field, preventing user interaction and form submission.
- `readonly` (`boolean`): Makes the input field read-only, allowing selection but preventing modification.
- `id` (`string`): Unique identifier for the input element, used for form labels and accessibility.
- `error` (`boolean`, default: `false`): Applies error styling (red border and text) to indicate validation failure.
- `success` (`boolean`, default: `false`): Applies success styling (green border and text) to indicate successful validation.
- `warning` (`boolean`, default: `false`): Applies warning styling (orange border and text) to indicate potential issues.
- `hint` (`string`): Alternative text that replaces the label when provided. Useful for contextual hints.
- `input-classes` (`string`): Additional CSS classes to apply specifically to the input wrapper element.
- `border` (`boolean`, default: `true`): Controls whether the input has a visible border. Set to false for borderless inputs.
- `inputmode` (`"none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal"`, default: `"text"`): HTML inputmode attribute that provides hints for virtual keyboards on mobile devices.
- `size` (`"xs" | "sm" | "md" | "lg" | "xl" | "mini"`): Controls the height and text size of the input component.
- `debounce` (`number | boolean`, default: `false`): Enables input debouncing to limit the frequency of value updates. When true, uses 500ms delay. When a number, uses that value as delay in milliseconds.
- `auto-focus` (`boolean`, default: `false`): Automatically focuses the input when the component mounts.
- `border-active` (`boolean`, default: `false`): When true, shows the colored border immediately instead of only on focus.
- `start-icon` (`MazIconLike`): Icon displayed on the inline-start edge of the input (left in LTR, right in RTL). Accepts a bare value (Vue component, raw SVG string, URL or `data:` URI) or a full `MazIconProps` object for fine-grained control (size, title, svgAttributes, fallback, …).
- `end-icon` (`MazIconLike`): Icon displayed on the inline-end edge of the input (right in LTR, left in RTL). Accepts a bare value or a full `MazIconProps` object.
- `rounded-size` (`MazRoundedSize`, default: `'md'`): Controls the border radius of the input component. Values: `'none'`, `'sm'`, `'md'`, `'lg'`, `'xl'`, `'full'` (non exhaustive).
- `block` (`boolean`): Makes the input expand to the full width of its container.
- `name` (`string`): The name of the input field. Used for form submission and validation.
- `autocomplete` (`string`): The autocomplete attribute for the input field. Used for form submission and validation.
- `loading` (`boolean`, default: `false`): Loading state for the input field. Used to show a loading spinner.

### Events

- `@update:model-value` (payload: `value?: T | undefined`): Triggered when the input value changes, used for v-model two-way binding. This event is debounced if the debounce prop is enabled
- `@click` (payload: `event: Event`): Triggered when the user clicks on the input field
- `@blur` (payload: `event: Event`): Triggered when the input field loses focus (user clicks outside or tabs away)
- `@change` (payload: `event: Event`): Triggered when the input value changes and the field loses focus. Different from input event which fires on every keystroke
- `@focus` (payload: `event: Event`): Triggered when the input field gains focus (user clicks or tabs into the field)
- `@input` (payload: `event: Event`): Triggered on every keystroke or input interaction (real-time input changes). This is the raw input event, not debounced

### Slots

- `#start-icon`: Custom content for the inline-start edge of the input field (left in LTR, right in RTL).
- `#end-icon`: Custom content for the inline-end edge of the input field (right in LTR, left in RTL).
- `#loader`: Loader slot.