Uploader Widget

Our uploader widget is a simple yet powerful tool that allows users to upload images with ease. It can be easily integrated into any web application, using either a React component or pure HTML, making it an ideal solution for developers who want to add image uploading capabilities to their web apps without the need for complex coding or external libraries.

The widget has the ability to seamlessly integrate with existing images, even making them editable. This means that users can easily migrate to the widget without having to worry about losing any of their existing images or disrupting their workflow.

One of the key features of the uploader widget is its seamless integration with our manager and editor. This means that users can easily manage and edit all of their uploaded images from a single, centralized location, streamlining their workflow and saving them time.

In addition, it is designed with security in mind, using SSL encryption to keep user data safe during transfer. Our platform is also regularly audited and tested to ensure that it meets the highest security standards.

Also, we provide the capacity to personalize the uploader to fit the color scheme of any web application, appearing as a natural part of the overall design. Ensuring that the uploader not only meet the functional needs of the application but also its aesthetic needs, reflecting our commitment to providing an intuitive and user-friendly experience.

Finally, it is optimized for speed and reliability, with advanced caching and compression algorithms that ensure that images are delivered quickly and efficiently to users around the world. This improves the overall performance and user experience of web applications.

In summary, the uploader widget is a fast, reliable, and easy-to-use solution for anyone who needs to upload and manage images on the web. With its simple integration, direct integration with our images manager and editor, robust security features, and optimized performance, it is the perfect solution for developers who want to add image uploading capabilities to their web applications.

Take a moment to review the available parameters to customize its behavior and appearance. By familiarizing yourself with the various customization options, you can tailor the widget to best suit your needs and provide a seamless user experience for your website visitors. There are a number of ways you can fine-tune the widget to meet your requirements. Take a look at the available parameters to get started!"


stringPublic API Key

API Key

The apiKey parameter is used to authenticate the widget and ensure that only authorized users can access it. It is a unique string of characters that is generated when the user creates an account and generates an API Key in the admin panel of the platform.

This key is required to make any changes or updates to the widget, such as uploading or deleting images.

To use the apiKey parameter, simply add it to the widget code along with the other parameters.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'/>

stringSet Thumbnail Shape

Aspect

The aspect property determines the shape of the thumbnails that are displayed in the uploader widget. By default, the thumbnails are square, but you can set the aspect property to either tall or wide to change the shape of the thumbnails accordingly.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	aspect='tall'/>

aspect="square"

aspect="tall"

aspect="wide"


stringAdjust Image to Specified Aspect Ratio

Aspect Ratio

When set, the aspectRatio parameter will automatically crop uploaded images to match the specified aspect ratio, ensuring that images conform to a specific size and shape.

For example, if you set the aspectRatio parameter to 9:16, the uploaded image will be cropped to a 9:16 aspect ratio. This means that the image will be resized and any excess portions of the image will be automatically cropped to match the aspect ratio.

By using the aspectRatio parameter, you can ensure that all of the uploaded images are consistent in size and shape, regardless of the aspect ratio of the original image. This can be especially useful if you're using uploaded images in a layout that requires them to be of a specific size or aspect ratio.

It's important to note that when you use the aspectRatio parameter, the editor will be locked to the specified aspect ratio by default. This means that users will not be able to change the aspect ratio when editing the image, unless you explicitly set the aspectRatioLocked parameter to false.

If you do set aspectRatioLocked to false, users will be able to change the aspect ratio when editing the image. However, if they do so, the resulting image may not match the aspect ratio specified in the aspectRatio parameter. In this case, the image will be resized and any excess portions will be automatically cropped to match the new aspect ratio selected by the user.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	aspectRatio='9:16'/>

aspectRatio="1:1"

aspectRatio="9:16"


booleanAllow Change Aspect Ratio in Editor

Aspect Ratio Locked

The aspectRatioLocked parameter is a boolean that can be used to control whether or not the editor should be locked to the aspect ratio specified in the aspectRatio parameter.

By default, when you use the aspectRatio parameter, the editor will be locked to the specified aspect ratio. This means that users will not be able to change the aspect ratio when editing the image. However, if you set the aspectRatioLocked parameter to false, users will be able to change the aspect ratio when editing the image.

Aspect Ratio Selector at Editor

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	aspectRatio='9:16'/>

aspectRatioLocked=true

aspectRatioLocked=false


stringAdd Widget ClassNames

Classname

The className parameter is a prop that can be used with the widget to add custom CSS class names to the widget's HTML element.

This can be useful if you want to apply your own custom styles to the widget, or if you want to integrate the widget into an existing CSS framework or component library.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	className='p-6 rounded-md'/>

className="p-6 rounded-md"


stringSet Widget Background's Color

Background Color

The backgroundColor parameter is a string that represents the background color of the uploader widget. It can be set to any valid CSS color value, such as a color name or a hexadecimal code.

By default, the widget background is transparent. However, setting the backgroundColor parameter can help integrate the widget seamlessly into the overall design of your web application.

The backgroundColor parameter can be used in combination with the textColor and thumbnailBackgroundColor parameter to control the color of the widget text. Together, these parameters can create a cohesive look and feel for the uploader widget, ensuring it fits in well with the rest of your application's design.

Snippet

import Uploader from '@simpleimg/uploader-react';

const [
	value,
	setValue
] = useState('ecba06a46b878d77f9765f1b7652791d.1.jpg');

<Uploader apiKey='YOUR_API_KEY'
	backgroundColor='#312e81'
	max={3}
	textColor='#eef2ff'
	thumbnailBackgroundColor='#1e1b4b'
	value={value}/>

backgroundColor="#312e81"


booleanAllow Direct Uploads

Direct Upload

The directUpload parameter is a boolean that can be used to allow for direct image uploads without the need for to open the image manager.

When directUpload is set to true, users can simply click on the uploader widget and select an image from their local device to upload.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	directUpload={true}/>

directUpload=true

directUpload=false


stringSet Widget Lang

Lang

The lang parameter is used to set the language of the widget interface. It can be set to either en-us for English (US) or pt-br for Portuguese (Brazil).

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	lang='en-us'/>

booleanSet Widget Lazy

Lazy

The lazy parameter is a boolean option that can be used to enable or disable lazy loading of the uploader widget. When lazy is set to true, the uploader widget will only be loaded when it is almost visible on the page, which can improve page loading times and reduce bandwidth usage.

However, it is not recommended to disable lazy loading, as it may negatively impact page performance and user experience, especially on slower internet connections or less powerful devices.

The lazy parameter is true by default, meaning that the uploader will only be loaded when it is almost visible in the viewport.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	lazy={true}/>

stringSet Manager Accent Color

Manager Accent Color

The managerAccentColor parameter is a string value that represents a color used to change the accent color for the image manager. By default, the accent color is set to blue. This parameter can be used to customize the color of primary buttons and other details in the image manager to match the branding of the web application.

Custom Accent Color at Uploads Manager

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	managerAccentColor='#d7006c'/>

managerAccentColor="#d7006c"


stringSet Manager Background Color

Manager Background Color

The managerBackgroundColor parameter is used to define the background color for the uploader's manager interface. It takes a string representing a valid color value, such as a hex code or a color name. By default, the background color is set to white when light mode, and gray if dark. This parameter can be used to customize the look and feel of the manager to match the overall design of the web application.

Custom Background Color at Uploads Manager

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	managerBackgroundColor='#1f2937'/>

managerBackgroundColor="#1f2937"


stringSet Manager Theme

Manager Theme

The managerTheme parameter is used to set the color theme of the uploader's manager. It can be set to auto, light or dark. When set to auto, the theme will be automatically selected based on the user's system settings (light or dark mode). When set to light, the manager will have a light color theme with white background and dark text. When set to dark, the manager will have a dark color theme with dark background and light text.

This parameter allows you to customize the look and feel of the manager to match the design of your application. If managerTheme is not defined, it will follow the value defined by the theme parameter of the uploader.

Dark Theme at Uploads Manager
Light Theme at Uploads Manager

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	managerTheme='dark'/>

managerTheme="dark"


stringSet Manager Title

Manager Title

The managerTitle parameter is a string that can be used to personalize the title of the image manager that appears when the user clicks on the widget.

By default, the title of the image manager is "nothing", but with the managerTitle parameter, you can customize it to better fit your application's needs.

Custom Title at Uploads Manager

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	managerTitle='Your Custom Title'/>

managerTitle="Your Custom Title"


numberSet Maximum Images

Max

The max parameter is used to define the maximum number of images that can be selected. This parameter accepts a number, where max=1 means only a single image can be selected and max=10 means that multiple images can be selected, with a maximum of 10 images.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	max={3}/>

max=3


numberSet Maximum Image Height

Max Height

The maxHeight parameter that allows you to set a maximum height for the images being selected. This parameter is particularly useful if you want to ensure that all the images in your application are the same size, or if you want to limit the size of images that users can select.

When maxHeight is set, any images that exceed this height will be automatically scaled down to fit within the limit. This can be helpful in preventing large files from being uploaded and slowing down your application.

Note that while the maxHeight parameter can be used to limit the maximum height of selected images, we generally discourage its use. This is because you can manipulate the image on the fly via CDN, using the height or maxHeight parameter.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	maxHeight={200}/>

maxHeight=200


numberSet Maximum Image Width

Max Width

The maxWidth parameter that allows you to set a maximum width for the images being selected. This parameter is particularly useful if you want to ensure that all the images in your application are the same size, or if you want to limit the size of images that users can select.

When maxWidth is set, any images that exceed this width will be automatically scaled down to fit within the limit. This can be helpful in preventing large files from being uploaded and slowing down your application.

Note that while the maxWidth parameter can be used to limit the maximum width of selected images, we generally discourage its use. This is because you can manipulate the image on the fly via CDN, using the width or maxWidth parameter.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	maxWidth={200}/>

maxWidth=200


functionCallback Function

OnChange

It is a callback function that is called whenever the user selects or uploads new images using the uploader. This parameter can be used to handle the new image data returned by the widget and update the state of the parent React component accordingly.

If responseType is set to string, the function will return a string or an array of strings containing the URLs of the uploaded images. If responseType is set to object, the function will return a ImageObject or an array of ImageObject's, which contain information about the uploaded images such as their URLs, dimensions, and other metadata.

Snippet

import Uploader from '@simpleimg/uploader-react';

const [
	value,
	setValue
] = useState('ecba06a46b878d77f9765f1b7652791d.1.jpg');

<Uploader apiKey='YOUR_API_KEY'
	onChange={setValue}
	responseType='string'
	value={value}/>

value="ecba06a46b878d77f9765f1b7652791d.1.jpg"


eventEvent/Callback Function

OnChangeEvent

The simple-img-uploader-change event is emitted by the node attached to the uploader whenever the value of the uploader is changed. The e.detail property of the event object contains an object with two properties: images and urls.

The images property is an array of ImageObject's, which contain information about the uploaded image(s) such as the image's name, size, type, width, and height, as well as the url of the uploaded image.

The urls property is an array of strings, which contain the URLs of the uploaded image(s).

You can use this event to perform additional actions whenever an image is uploaded or removed.

Snippet

<script id="simple-img-uploader-js"
	data-api-key="YOUR_API_KEY"
	src="https://static.simpleimg.io/uploader-js/index.js"></script>

<input data-simple-img-uploader
	type="hidden"/>

<script>
	const node = document.querySelector('[data-simple-img-uploader]');

	node.addEventListener('simple-img-uploader-change', e => {
		const images = e.detail.images; /* Array<ImageObject> */
		const urls = e.detail.urls; /* Array<string> */

		// Perform additional actions here, such as displaying the uploaded images.
	});
</script>

booleanPrepend Images

Prepend

The prepend parameter can be used with the uploader widget when uploading multiple images. By default, new images are appended to the list of already uploaded images. However, when the prepend parameter is set to true, new images will be inserted at the beginning of the list instead of being appended. This can be useful in certain scenarios, such as when you want to prioritize the most recent images.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	max={3}
	prepend={true}/>

prepend=true


stringSet Uploader Response Type

Response Type

The responseType parameter allows you to define the format of the response you receive from the uploader.

By default, responseType is set to object, the response you receive from the uploader will include detailed information about the image, including its dimensions, format, URL, and other metadata. This information is returned as an ImageObject, a structured data type that provides a convenient way to access and manipulate image data in your web application.

When, responseType is set to string, which means that the uploadder will return only the URLs of the images as plain text strings.

Using the responseType parameter, you can customize the behavior the uploader widget to suit the specific needs of your application.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	onChange={value => {
		console.log(value);
	}}
	responseType='string'/>

responseType="string"

String Response

https://demo.simpleimg.io/ecba06a46b878d77f9765f1b7652791d.1.jpg

responseType="object"

Object Response

{
	"blurHash": "LiPG58_%MyKitRayf6f6V[ayWUbG",
	"colors": [
		{
			"count": 11,
			"hex": "#cb9890",
			"name": "brown",
			"type": "Vibrant"
		},
		{
			"count": 12572,
			"hex": "#f9c0bc",
			"name": "orange",
			"type": "LightVibrant"
		},
		{
			"count": 97,
			"hex": "#7d9887",
			"name": "green",
			"type": "Muted"
		},
		{
			"count": 2364,
			"hex": "#add8d2",
			"name": "blue",
			"type": "LightMuted"
		}
	],
	"contentLength": 261908,
	"contentType": "image/jpeg",
	"createdAt": 1678380259110,
	"extension": "jpg",
	"height": 1281,
	"id": "ecba06a46b878d77f9765f1b7652791d",
	"putAt": 1678205645294,
	"updatedAt": 1678380259110,
	"version": 1,
	"width": 1920,
	"url": "https://demo.simpleimg.io/ecba06a46b878d77f9765f1b7652791d.1.jpg"
}

numberAdjust Thumbnail Rounded

Rounded

The rounded parameter is used to define the rounded effect on the image thumbnails displayed by the uploader widget. It accepts a number from 0 to 5, with higher numbers producing a more pronounced rounded effect. A value of 0 means the thumbnail is square, 1 means is slightly rounded, while a value of 5 creates a circular thumbnail. This parameter is purely aesthetic and does not affect the functionality of the uploader.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	rounded={5}/>

rounded=1

rounded=5

max=2; rounded=5


stringCustom HTML Selector

Selector

The selector parameter is used to change the default HTML selector used by the widget in the HTML implementation. By default, the widget binds to all input elements with the data-simple-img-uploader attribute.

If you want to use a different selector, you can set the selector parameter to a custom CSS selector string. For example, if you want to bind the widget to all elements with the class .custom-uploader, you can set the selector=".custom-uploader".

Additionally, you can programmatically initialize the widget with a custom selector using the window.simpleImgUploaderInit({ selector: ".custom-uploader" }) method. This will initialize the widget to all elements with the .custom-uploader class. Once initialized, the widget will bind to the specified elements and allow users to upload images.

Snippet

<script id="simple-img-uploader-js"
	data-api-key="YOUR_API_KEY"
	data-selector=".custom-uploader"
	src="https://static.simpleimg.io/uploader-js/index.js"></script>

<input class="custom-uploader"
	type="hidden"/>

numberAdjust Thumbnail Shadow

Shadow

The shadow parameter is used to add a shadow effect to the thumbnail images displayed in the widget. It accepts values from 0 to 2, where 0 means no shadow and 2 means a more pronounced shadow effect. By default, the shadow effect is set to 1.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	shadow={2}/>

shadow=1

shadow=2


numberAdjust Thumbnail Size

Size

The size parameter is used to set the thumbnail size in the uploader widget. It ranges from 1 to 5, with 1 being the smallest size and 5 being the largest. This parameter affects only the visual representation of the thumbnail in the widget, it doesn't affect the actual size of the uploaded image.

By default, the size parameter is set to 1, which provides a small-sized thumbnail. However, you can adjust the size of the thumbnail to best fit the design and layout of your application.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	size={2}/>

size=1

size=3

size=5


booleanToggle Sortable

Sortable

The sortable parameter is a boolean that determines whether multiple images can be sorted within the widget. When sortable is set to true, users can drag and drop images to rearrange their order. This can be useful for organizing a collection of images, such as a photo album or gallery.

However, if sortable is set to false, images will be displayed in the order in which they were selected and users will not be able to change their position within the widget. It's worth noting that if max is set to 1, then sortable has no effect since only a single image can be selected at a time.

Overall, the sortable parameter provides additional flexibility and control to the image uploading process, allowing users to easily organize their images within the widget.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	max={3}
	sortable={true}/>

sortable=true

sortable=false


object|stringApply CSS Styles

Style

The style parameter allows customization of the widget through CSS properties. When using the React uploader component, the style parameter should be an object that contains the CSS properties and values to be applied to the widget. When using the HTML implementation, the style parameter should be a string that contains the CSS rules to be applied to the widget.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	style={{
		backgroundColor: 'whitesmoke'
	}}/>

style={backgroundColor: "whitesmoke"}


stringChange Widget Description

Text

The text parameter allows you to change the description text of the widget. This parameter can be used to add more information about the expected image size, format, or any other relevant details. It is displayed above the uploader widget.

In addition, the mobileText parameter allows you to set a different description text for mobile devices. This can be useful to provide a more concise or mobile-optimized description. When mobileText is set, it overrides the text parameter on mobile devices.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	text='Your Custom Text'/>

text="Your Custom Text"


stringSet Widget Text's Color

Text Color

The textColor parameter is used to define the color of the text in the uploader widget. It accepts a string representing a CSS color value, like #ffffff for white or #2dd4bf for teal.

This parameter can be useful for ensuring the text in the widget is easily visible against different backgrounds or for branding purposes. If not defined, the default text color will be used.

The textColor parameter can be used in combination with the backgroundColor and thumbnailBackgroundColor parameter to control the background color of the widget. Together, these parameters can create a cohesive look and feel for the uploader widget, ensuring it fits in well with the rest of your application's design.

Snippet

import Uploader from '@simpleimg/uploader-react';

const [
	value,
	setValue
] = useState('ecba06a46b878d77f9765f1b7652791d.1.jpg');

<Uploader apiKey='YOUR_API_KEY'
	backgroundColor='#4c1d95'
	max={3}
	textColor='#faf5ff'
	thumbnailBackgroundColor='#3b0764'
	value={value}/>

textColor="#faf5ff"


stringSet Widget Theme

Theme

The theme parameter can be set to auto, dark, or light to control the theme of the widget. If the managerTheme parameter is not defined, the theme parameter will apply to the image manager as well.

If the theme is set to auto, the widget will use the theme defined by the user's operating system. If the theme is set to dark, the widget will use a dark theme with white text and accents in a dark color. If the theme is set to light, the widget will use a light theme with black text and accents in a light color.

The theme parameter can be combined with the backgroundColor and textColor parameters to fully customize the appearance of the widget.

Snippet

import Uploader from '@simpleimg/uploader-react';

const [
	value,
	setValue
] = useState('ecba06a46b878d77f9765f1b7652791d.1.jpg');

<Uploader apiKey='YOUR_API_KEY'
	max={3}
	theme='dark'
	value={value}/>

theme="dark"


stringSet Widget Thumnbail's Background Color

Thumbnail Background Color

The thumbnailBackgroundColor parameter is used to define the background color of the thumbnails displayed in the widget. By default, the background color is a semi-transparent white or dark layer, depending on the selected theme. However, this can be customized by setting the thumbnailBackgroundColor parameter to a string representing the desired color.

This parameter can be used together with backgroundColor andtextColor to create a visually cohesive design for the widget. For example, setting thumbnailBackgroundColor to a shade of blue and textColor to a contrasting white can create a visually appealing widget.

You can use this parameter to customize the look of your uploader widget and make it more consistent with your web application's color scheme.

Snippet

import Uploader from '@simpleimg/uploader-react';

const [
	value,
	setValue
] = useState('ecba06a46b878d77f9765f1b7652791d.1.jpg');

<Uploader apiKey='YOUR_API_KEY'
	backgroundColor='#1e3a8a'
	max={3}
	textColor='#eff6ff'
	thumbnailBackgroundColor='#172554'
	value={value}/>

thumbnailBackgroundColor="#eff6ff"


stringChange Widget Title

Title

The title parameter is used to change the title of the widget. It allows you to customize the title to better fit the context of your application or website. When using the title parameter, the widget will display the custom title instead of the default one.

For mobile devices, there is a separate parameter called mobileTitle. This parameter allows you to customize the title specifically for mobile devices. This is useful if you want to display a shorter or more concise title on smaller screens.

Both the title and mobileTitle parameters accept a string value, which should be the desired title text.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	title='Your Custom Title'/>

title="Your Custom Title"


stringPartitionate User Space

User

The user parameter is a string value that can be used to partition the image uploads into multiple user spaces. This can be useful in scenarios where you have a system that allows multiple users to upload images and you want to keep the images separate for each user.

When you use the user parameter, the images uploaded by each user will be stored in a separate directory that is named with a hash of user's ID. This allows you to easily manage and retrieve images for each user separately.

For example, if you have two users with IDs user-1 and user-2 and they both upload images using the same uploader widget, you can specify the user parameter with their respective IDs. The images uploaded by user-1 will be stored in a directory named with a hash of user-1 and the images uploaded by user-2 will be stored in a directory named with a hash of user-2.

By using the user parameter, you can easily keep track of which images belong to which user and provide a better user experience for your users.

Snippet

import Uploader from '@simpleimg/uploader-react';

<Uploader apiKey='YOUR_API_KEY'
	user='user-1'/>

string|ImageObjectSet Initial Value

Value

The value parameter is used to set the initial value of the widget. It can be a string representing the URL of a single image or an array of strings representing the URLs of multiple images. Alternatively, for react users, it can be an ImageObject representing a single image or an array of ImageObject's representing multiple images.

When using the value parameter, the widget will display the provided image(s) or image placeholder(s) on initial render. This is useful when editing an existing record that already has an image(s) associated with it.

Snippet

import Uploader from '@simpleimg/uploader-react';

const [
	value,
	setValue
] = useState('ecba06a46b878d77f9765f1b7652791d.1.jpg');

<Uploader apiKey='YOUR_API_KEY'
	onChange={setValue}
	responseType='string'
	value={value}/>

value="ecba06a46b878d77f9765f1b7652791d.1.jpg"