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!"
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'/>
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"
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"
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.
Snippet
import Uploader from '@simpleimg/uploader-react';
<Uploader apiKey='YOUR_API_KEY'
aspectRatio='9:16'/>
aspectRatioLocked=true
aspectRatioLocked=false
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"
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"
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
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'/>
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}/>
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.
Snippet
import Uploader from '@simpleimg/uploader-react';
<Uploader apiKey='YOUR_API_KEY'
managerAccentColor='#d7006c'/>
managerAccentColor="#d7006c"
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.
Snippet
import Uploader from '@simpleimg/uploader-react';
<Uploader apiKey='YOUR_API_KEY'
managerBackgroundColor='#1f2937'/>
managerBackgroundColor="#1f2937"
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.
Snippet
import Uploader from '@simpleimg/uploader-react';
<Uploader apiKey='YOUR_API_KEY'
managerTheme='dark'/>
managerTheme="dark"
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.
Snippet
import Uploader from '@simpleimg/uploader-react';
<Uploader apiKey='YOUR_API_KEY'
managerTitle='Your Custom Title'/>
managerTitle="Your Custom Title"
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
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
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
OnChange
Exclusive parameter for the React version of the uploader.
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.
When using HTML integration, the value of the <input type="hidden" />
element will be automatically updated with the image URLs selected by the user,
separated by commas if multiple images were selected. This allows the form to be submitted with the selected images.
For advanced HTML integration see OnChangeEvent
.
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"
OnChangeEvent
Exclusive implementation for the HTML version of the uploader.
The simple-img-uploader-change
event can be used to create integrations with other libraries or frameworks than React.
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>
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
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.
The responseType
parameter is only applicable to the React component implementation of the uploader widget.
When using the pure HTML implementation, the response type defaults to string.
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"
}
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
Selector
Exclusive parameter for the HTML version of the uploader.
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.
The window.simpleImgUploaderInit({ selector: ".custom-uploader" })
call can be used to create integrations with other libraries or frameworks than React.
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"/>
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
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
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
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"}
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"
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"
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"
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"
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"
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'/>
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.
When using HTML integration, the value of the <input type="hidden" />
element will be automatically updated with the image URLs selected by the user,
separated by commas if multiple images were selected. This allows the form to be submitted with the selected images.
For advanced HTML integration see OnChangeEvent
.
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}/>