Unsplash page

demo: https://massimo-cassandro.github.io/unsplash-page/demo

Single page with random photo from Unsplash to display some messages (useful for error pages).

This component comes from some experiments I did with the Unsplash API. The initial purpose was to display more appealing error pages, but you can use it for any use.

For best results, it is advisable to display images from a photo collection prepared on Unsplash. The demos in this repository use my collection "World".

You need to create a server script to retrieve the JSON data of a random image from Unsplash (see Get a Random Photo on Unsplash API docs).

The script also implements BlurHash, to show a placeholder of the image until it loads.

For more details and examples take a look at:

• https://unsplash.com/developers
• A Random Image Slideshow With Unsplash and React
• Unsplash Random Photo 1
• Random Unsplash Photos Slideshow
• A Split Image Effect in React and split image

The SVG icons used in the script are from Phosphor Icon. At the moment it is not possible to use different ones without modifying the source code.

Installation

Install from NPM:

npm i -S  @massimo-cassandro/unsplash-page blurhash

Fro info about blurhash: https://www.npmjs.com/package/blurhash.

Running a local demo

Launch a php server (php needed for data proxy), then go to the demo dir:

php -S localhost:8000

and then open http://localhost:8000/demo/.

Use

Demo: https://massimo-cassandro.github.io/unsplash-page/demo/vanilla-js/index.html

Add to your script:

import { unsplashPageJS } from '@massimo-cassandro/unsplash-page';


unsplashPageJS({
  targetElement    : document.getElementById('root'),
  className        : 'class',
  unsplashDataUrl  : 'url',
  utmSource        : 'source',
  title            : 'Message title',
  text             : 'This is the message <strong>text</strong>',
  backLink         : '<a href="link/to/home">Back to home</a>',
  hidePhotoLink    : true,
  cssModules       : false,
  cssModulesObj    : null
});

where:

• className, unsplashDataUrl, utmSource and hidePhotoLink correspond exactly to what is described in the React version
• title, text and backLink are like the previous ones, but in this case they are always strings
• targetElement: The DOM element in which to insert the necessary markup
• cssModules: Set to true if your bundler uses CSS Modules (default false)
• cssModulesObj: If you are using CSS Modules, assign to these parameter the imported styles object (see below).

CSS

The JS file does not include any CSS, to maintain maximum flexibility of use.

Then you can plug your CSS into the html (like I did in the demo) or manage it with Rollup, Webpack etc.

If you are using CSS modules, you need to share the parsed CSS object with the script so that the processed class names can be used:

import styles from '@massimo-cassandro/unsplash-page/src/unsplash-page.module.css';

unsplashPageJS({
  /* ... */
  cssModules       : true,
  cssModulesObj    : styles
});

SVG icons

SVG icons are imported into the script, both in the React and Vanilla JS versions.

In the latter, they need to be managed by your bundler to ensure they load correctly. In the demo, I used @rollup/plugin-image to import them as base64. Since they are very small, this seems to be the simplest solution.

CSS customization

You can customize the CSS (fonts, colors, etc.) using some CSS custom properties.

You need to provide them as a separate CSS file to change the default settings.

Below you can see the list of properties set with their default values: simply reset the ones you want to change and ignore the others.

You can do this by setting variables in the :root element, or you can narrow their scope to the component container by assigning it a class (thru the className parameter) and then using it in you CSS.

For a complete list of all custom properties see src/unsplash-page.modules.css;

/* needed if your script doesn't embed the css file */
@import '@massimo-cassandro/unsplash-page/src/unsplash-page.module.css';

.your-custom-class { /* or :root */

  /* your css custom props */
}

Using http error codes

Using HTTP Error Codes from your server can be a clever way to use this component.

First, get the error code from your server (404, 500, etc.), for example by setting it as a data attribute somewhere, then pass it to the script that implements UnsplashPage. Matching the errorCode with an object of predefinited titles and text, can do the trick:

const myErrorCode = +document.body.dataset.errorCode || 500;

const errorTypes = {
  403: {
    title: 'Oops… You can’t access this page', 
    // title: 'Ops… Non puoi accedere a questa pagina',
    text: null
  },
  404: {
    title: 'Oops… This page does not exist', 
    // title: 'Ops… Questa pagina non esiste',
    text: null
  },
  500: {
    title: 'Oops… An error has occurred', 
    // title: 'Ops… Si è verificato un errore',
    text: null
  },
  503: {
    title: 'Sorry, this site is temporarily under maintenance', 
    // title: 'Siamo spiacenti, il sito è temporaneamente in manutenzione',
    text: null
  }
};

unsplashPageJS({
  /* ... */
  title: errorTypes[myErrorCode].title,
  text: errorTypes[myErrorCode].text,
  backLink: myErrorCode !== 503? <a href="link/to/home">Back to home</a> : null

});

Use with React

The previous version of UP contained a React version of the script, but, to simplify maintenance and achieve maximum flexibility of use, I now prefer to use a React wrapper of the Vanilla JS script: you can find a template of the file in the react folder.

The sample uses React Router to display error messages based on server results.

In the same folder, you can find the previous, unmantained, React version,

Images breakpoints & sizes

Images are uploaded at different sizes using the Unsplash API. Other than a few differences, CSS media query breakpoints are the same as those in Bootstrap 5.

The following table reports the image size for each breakpoint:

| BS5 breakpoint | xs | sm | md | lg | xl | xxl | |------------------------------|:-----:|:--------:|:---------:|:----------:|:-----------:|:------:| | Page width | < 576 | 576 -767 | 768 - 991 | 992 - 1199 | 1200 - 1399 | >=1400 | | img width | 576 | 768 | 992 | 1200 | 1400 | 1920 | | img height (16/9) | 324 | 432 | 558 | 675 | 788 | 1080 | | img height (4/3) | 432 | 576 | 744 | 900 | 1050 | 1440 | | img height (9/21, portrait) | 1344 | | | | | | | img height (21/9, landscape) | 247 | | | | | |

Sizes and breakpoints are defined in the img-breakpoints.js file.