Pixabay Images Gallery

A free JavaScript widget for inserting Pixabay image galleries with ease into any website or blog.

This widget may be used without charge for any application - also commercial and without giving credits. The image galleries are easily customizable and they are responsive by default. The images themselves are released under the Pixabay License.

The widget's code is released under the MIT License as free Open Source on Github. It works in Firefox, Chrome, Safari, Opera and Internet Explorer 8+ and it has no dependencies (plain JavaScript).

Download View on GitHub

How to use

First, sign up on Pixabay and get your API key, which you'll find on the API documentation page. Signing up is free, of course. Then, include the JavaScript including your API key anywhere on the page, but preferably before the closing </body> tag.

<script>var pixabayWidget = { 'key': 'YOUR_PIXABAY_API_KEY' }</script>
<script src="https://goodies.pixabay.com/javascript/pixabay-widget/pixabay-widget.min.js" async defer></script>

The script automatically detects all widget containers and renders the image galleries. A widget container looks like this:

<div class="pixabay_widget" data-search="africa animals" data-max-rows="3"></div>

The resulting widget shows a set of popular Pixabay images, matching the term "africa animals", and including navigation buttons with branding:

The attribute data-search tells the widget what images to search for. When omitting this parameter, all Pixabay images are listed. data-max-rows limits the widget to a maximum of three rows of images. The following table lists all available data-* settings:

HTML5 data attribute settings

data-search''A string to search for. Maximum length: 100 characters. Omit to select all images.
data-user''A Pixabay username to limit search results to.
data-lang'en'The language to search in. Accepted values: 'bg', 'cs', 'da', 'de', 'el', 'en', 'es', 'fi', 'fr', 'hu', 'id', 'it', 'ja', 'ko', 'nl', 'no', 'pl', 'pt', 'ro', 'ru', 'sk', 'sv', 'th', 'tr', 'vi', 'zh'
data-image-type'all'A media type to search within. Accepted values: "all", "photo", "illustration".
data-safesearchfalseA flag indicating that only images suitable for all ages should be returned. Accepted values: "true", "false".
data-editors-choicefalseSelect images that have received an Editor's Choice award. Accepted values: "true", "false".
data-order'popular'How the results should be ordered. Accepted values: "popular", "latest".
data-page1Returned image sets are paginated. Use this parameter to select the page number.
data-per-page20Maximum number of images per next/prev page. Values: 3-100.
data-row-height170Maximum height of a row in pixels. Values 30-180.
data-max-rows-Maximum number of rows to display. Images exceeding this row are hidden.
data-truncatefalseHide incomplete last row of images.
data-target-Link target for images, e.g. "_blank."
data-navpos'bottom'Position of pagination links and branding. Leave empty to hide both. Accepted values: "bottom", "top".
data-brandingtrueWhether to show "Powered by Pixabay". Accepted values: "true", "false".
data-prev'◄ PREV'Text for the "previous" link. Leave empty to hide pagination controls.
data-next'NEXT ►'Text for the "next" link. Leave empty to hide pagination controls.


A widget showing the most popular images by stevepb - only one row of large images, navigation on top and no branding:

<div class="pixabay_widget" data-user="stevepb" data-max-rows="1" data-row-height="180" data-branding="false" data-navpos="top"></div>

And that's how the gallery looks like:

Changing the default settings and the widget class name

Data attributes are used to configure individual widgets. As an alternative, it's also possible to modify the default settings. This is done by defining a global JavaScript object "pixabayWidget" before loading the widget script. These are the available parameters:

    var pixabayWidget = {
        class_name: 'pixabay_widget', // class name for detecting widgets on the page
        lang: 'en',
        image_type: 'all',
        safesearch: false,
        editors_choice: false,
        order: 'popular',
        per_page: 20,
        row_height: 170,
        max_rows: false,
        truncate: false,
        target: '',
        navpos: 'bottom',
        branding: true,
        prev: '◄ PREV',
        next: 'NEXT ►'

Updating widgets after DOM manipulations

New widgets may be added (e.g. via AJAX) and all attributes and settings may be modified at any time. Use the initPixabayWidget() method to render all changes.

    new initPixabayWidget();

Styles and layout

The widget comes with a default set of CSS rules, which is dynamically generated by the script. All CSS directives may be overwritten with custom styles. Please take a look at the widget's JavaScript source code to see the auto-generated CSS.

CDN source / Hosting the JavaScript code

If you like, you may download the script and host it on your own server(s). Alternatively, use the script URL from Pixabay - as shown in the example above. Or you can make use of RawGit to access the GitHub repository via CDN (MaxCDN):

<script src="https://cdn.rawgit.com/Pixabay/JavaScript-PixabayWidget/master/pixabay-widget.min.js" async defer></script>

This software is released as Open Source under the MIT License by Simon Steinberger / Pixabay.com.

About Us Blog More Goodies © Pixabay.com / Simon Steinberger / Hans Braxmeier