Documentation v1.1.5

Preview

Overview

Image input is an exclusive plugin of Craft that enables a simple, user-friendly and lightweight image input field.

Usage

Image input's CSS and Javascript files are bundled in the global style and scripts bundles and are globally included in all pages:
<link href="assets/css/style.bundle.css" rel="stylesheet" type="text/css"/>
<script src="assets/js/scripts.bundle.js"></script>

Initialization

  • Image input does not come with its own custom CSS and it uses global input controls and related elements.
  • Image input instances are automatically initialized through data-kt-image-input="true" HTML attribute on document ready event. However, some HTML markup is required to build the content and controls required. To initialize Image Input instance in Javascript remove data-kt-image-input="true" attribute and refer to KTImageInput class constructor below.
  • The HTML markup comes in a few sections:
    • Main wrapper
    • Image preview wrapper
    • Edit button
    • Cancel button
    • Remove button
  • The image preview wrapper element is identified by the .image-input-wrapper css class.
  • The edit button is identified by the data-kt-image-input-action="change" attribute.
  • The cancel button is identified by the data-kt-image-input-action="cancel" attribute.
  • The remove button is identified by the data-kt-image-input-action="remove" attribute.
  • Please refer to our basic example below for a sample HTML markup.
  • Image input instances can also be controlled programmatically with Javascript. See below for more info.

Basic Example

Basic example of an empty image input:
<!--begin::Image input placeholder-->
<style>
    .image-input-placeholder {
        background-image: url('svg/avatars/blank.svg');
    }

    [data-bs-theme="dark"] .image-input-placeholder {
        background-image: url('svg/avatars/blank-dark.svg');
    }                
</style>
<!--end::Image input placeholder-->

<!--begin::Image input-->
<div class="image-input image-input-empty" data-kt-image-input="true">
    <!--begin::Image preview wrapper-->
    <div class="image-input-wrapper w-125px h-125px"></div>
    <!--end::Image preview wrapper-->

    <!--begin::Edit button-->
    <label class="btn btn-icon btn-circle btn-color-muted btn-active-color-primary w-25px h-25px bg-body shadow"
    data-kt-image-input-action="change"
    data-bs-toggle="tooltip"
    data-bs-dismiss="click"
    title="Change avatar">
        <i class="ki-duotone ki-pencil fs-6"><span class="path1"></span><span class="path2"></span></i>

        <!--begin::Inputs-->
        <input type="file" name="avatar" accept=".png, .jpg, .jpeg" />
        <input type="hidden" name="avatar_remove" />
        <!--end::Inputs-->
    </label>
    <!--end::Edit button-->

    <!--begin::Cancel button-->
    <span class="btn btn-icon btn-circle btn-color-muted btn-active-color-primary w-25px h-25px bg-body shadow"
    data-kt-image-input-action="cancel"
    data-bs-toggle="tooltip"
    data-bs-dismiss="click"
    title="Cancel avatar">
        <i class="ki-outline ki-cross fs-3"></i>
    </span>
    <!--end::Cancel button-->

    <!--begin::Remove button-->
    <span class="btn btn-icon btn-circle btn-color-muted btn-active-color-primary w-25px h-25px bg-body shadow"
    data-kt-image-input-action="remove"
    data-bs-toggle="tooltip"
    data-bs-dismiss="click"
    title="Remove avatar">
        <i class="ki-outline ki-cross fs-3"></i>
    </span>
    <!--end::Remove button-->
</div>
<!--end::Image input-->

Outline Style

Sets the image preview wrapper with a bordered edge:
<!--begin::Image input placeholder-->
<style>
    .image-input-placeholder {
        background-image: url('svg/avatars/blank.svg');
    }

    [data-bs-theme="dark"] .image-input-placeholder {
        background-image: url('svg/avatars/blank-dark.svg');
    }                
</style>
<!--end::Image input placeholder-->

<!--begin::Image input-->
<div class="image-input image-input-outline" data-kt-image-input="true" style="background-image: url(/assets/media/svg/avatars/blank.svg)">
    <!--begin::Image preview wrapper-->
    <div class="image-input-wrapper w-125px h-125px" style="background-image: url(/assets/media/avatars/300-1.jpg)"></div>
    <!--end::Image preview wrapper-->

    <!--begin::Edit button-->
    <label class="btn btn-icon btn-circle btn-color-muted btn-active-color-primary w-25px h-25px bg-body shadow"
    data-kt-image-input-action="change"
    data-bs-toggle="tooltip"
    data-bs-dismiss="click"
    title="Change avatar">
        <i class="ki-duotone ki-pencil fs-6"><span class="path1"></span><span class="path2"></span></i>

        <!--begin::Inputs-->
        <input type="file" name="avatar" accept=".png, .jpg, .jpeg" />
        <input type="hidden" name="avatar_remove" />
        <!--end::Inputs-->
    </label>
    <!--end::Edit button-->

    <!--begin::Cancel button-->
    <span class="btn btn-icon btn-circle btn-color-muted btn-active-color-primary w-25px h-25px bg-body shadow"
    data-kt-image-input-action="cancel"
    data-bs-toggle="tooltip"
    data-bs-dismiss="click"
    title="Cancel avatar">
        <i class="ki-outline ki-cross fs-3"></i>
    </span>
    <!--end::Cancel button-->

    <!--begin::Remove button-->
    <span class="btn btn-icon btn-circle btn-color-muted btn-active-color-primary w-25px h-25px bg-body shadow"
    data-kt-image-input-action="remove"
    data-bs-toggle="tooltip"
    data-bs-dismiss="click"
    title="Remove avatar">
        <i class="ki-outline ki-cross fs-3"></i>
    </span>
    <!--end::Remove button-->
</div>
<!--end::Image input-->

Circle Style

Circle edge example of an image input:
<!--begin::Image input placeholder-->
<style>
    .image-input-placeholder {
        background-image: url('svg/avatars/blank.svg');
    }

    [data-bs-theme="dark"] .image-input-placeholder {
        background-image: url('svg/avatars/blank-dark.svg');
    }                
</style>
<!--end::Image input placeholder-->

<!--begin::Image input-->
<div class="image-input image-input-circle" data-kt-image-input="true" style="background-image: url(/assets/media/svg/avatars/blank.svg)">
    <!--begin::Image preview wrapper-->
    <div class="image-input-wrapper w-125px h-125px" style="background-image: url(/assets/media/avatars/300-20.jpg)"></div>
    <!--end::Image preview wrapper-->

    <!--begin::Edit button-->
    <label class="btn btn-icon btn-circle btn-color-muted btn-active-color-primary w-25px h-25px bg-body shadow"
    data-kt-image-input-action="change"
    data-bs-toggle="tooltip"
    data-bs-dismiss="click"
    title="Change avatar">
        <i class="ki-duotone ki-pencil fs-6"><span class="path1"></span><span class="path2"></span></i>

        <!--begin::Inputs-->
        <input type="file" name="avatar" accept=".png, .jpg, .jpeg" />
        <input type="hidden" name="avatar_remove" />
        <!--end::Inputs-->
    </label>
    <!--end::Edit button-->

    <!--begin::Cancel button-->
    <span class="btn btn-icon btn-circle btn-color-muted btn-active-color-primary w-25px h-25px bg-body shadow"
    data-kt-image-input-action="cancel"
    data-bs-toggle="tooltip"
    data-bs-dismiss="click"
    title="Cancel avatar">
        <i class="ki-outline ki-cross fs-3"></i>
    </span>
    <!--end::Cancel button-->

    <!--begin::Remove button-->
    <span class="btn btn-icon btn-circle btn-color-muted btn-active-color-primary w-25px h-25px bg-body shadow"
    data-kt-image-input-action="remove"
    data-bs-toggle="tooltip"
    data-bs-dismiss="click"
    title="Remove avatar">
        <i class="ki-outline ki-cross fs-3"></i>
    </span>
    <!--end::Remove button-->
</div>
<!--end::Image input-->

Markup Reference

Image input uses both CSS and HTML attributes to define the input configuration. The CSS classes below must be placed next to the main image-input css class within the main wrapper. Here are the references for each below
CSS classes references
Name Description
image-input Enables the image input component.
image-input-circle Sets the image preview wrapper with a circle edge.
image-input-outline Sets the image preview wrapper with a bordered edge.
Tip: The image-input-circle and image-input-outline classes can be used simultaneously.
HTML attribute references
Name Type Description
data-kt-image-input mandatory Accepts true and false values, when true is set KTImageInput Javascript class automatically initializes the image input instance to apply the edit & remove logic.
data-kt-image-input-action mandatory
To be applied to each button type. Accepts either change, cancel or remove values. This specifies the type of button it's assigned to.
Each button must be defined within the main wrapper of the image input.

Methods

All Image Input components are initialized automatically, however the following are the Image input's functionality methods for more control.
Name Description
Static Methods
createInstances(DOMString selector) Initializes Image Input instances by selector. Default value of selector is [data-kt-image-input]. This method can be used to initialize dynamicly populated Image Input instances(e.g: after Ajax request).
KTImageInput.createInstances();
getInstance(DOMElement element) Get the Image input instance created
var imageInputElement = document.querySelector("#kt_image_input_control");
var imageInput = KTImageInput.getInstance(imageInputElement);
Public Methods
Constructor Constructs a new instance of KTImageInput class and initializes an Image Input control:
var imageInputElement = document.querySelector("#kt_image_input_control");
var imageInput = new KTImageInput(imageInputElement);
Remove data-kt-image-input="true" attribute to avoid lazy initializes.
getInputElement Returns the selected image input instance input field.
imageInput.getInputElement();
goElement Returns the selected image input instance.
imageInput.goElement();

Events

Below are few events for hooking into the Image input functionality.
Event Type Description
kt.imageinput.change This event fires on when the image input is about to change.
var imageInputElement = document.querySelector("#kt_image_input_example_1");
var imageInput = KTImageInput.getInstance(imageInputElement);
imageInput.on("kt.imageinput.change", function() {
    // console.log("kt.imageinput.change event is fired");
});
kt.imageinput.changed This event fires on when the image input has been changed.
var imageInputElement = document.querySelector("#kt_image_input_example_1");
var imageInput = KTImageInput.getInstance(imageInputElement);
imageInput.on("kt.imageinput.changed", function() {
    // console.log("kt.imageinput.changed event is fired");
});
kt.imageinput.cancel This event fires on when the image input is about to get cancelled.
var imageInputElement = document.querySelector("#kt_image_input_example_1");
var imageInput = KTImageInput.getInstance(imageInputElement);
imageInput.on("kt.imageinput.cancel", function() {
    // console.log("kt.imageinput.cancel event is fired");
});
kt.imageinput.canceled This event fires on when the image input has been cancelled.
var imageInputElement = document.querySelector("#kt_image_input_example_1");
var imageInput = KTImageInput.getInstance(imageInputElement);
imageInput.on("kt.imageinput.canceled", function() {
    // console.log("kt.imageinput.canceled event is fired");
});
kt.imageinput.remove This event fires on when the image input is about to get removed.
var imageInputElement = document.querySelector("#kt_image_input_example_1");
var imageInput = KTImageInput.getInstance(imageInputElement);
imageInput.on("kt.imageinput.remove", function() {
    // console.log("kt.imageinput.remove event is fired");
});
kt.imageinput.removed This event fires on when the image input has been removed.
var imageInputElement = document.querySelector("#kt_image_input_example_1");
var imageInput = KTImageInput.getInstance(imageInputElement);
imageInput.on("kt.imageinput.removed", function() {
    // console.log("kt.imageinput.removed event is fired");
});
Preview Get Help Buy Now