A Material Design inspired showcase view that highlights any element on your page.
If you're using a module bundler such as Webpack or Browserify, you can use npm to install Showcaser:
npm install --save showcaser
and then you can simply import
/require
Showcaser:
import Showcaser from 'showcaser'
If you would like to load Showcaser using a script
tag, grab the latest version from the dist folder and include it in your page:
<body>
...
<script src="https://github.com/geocortex/showcaser/raw/master/showcaser.min.js"></script>
</body>
Check out the demo source code for more examples:
const myElement = document.getElementById("cool-element");
Showcaser.showcase("Here's Showcaser!", myElement);
This document uses Typescript-like definitions to describe interfaces. You can take a look at our Typescript definition file at dist/showcaser.d.ts.
Showcaser allows you to link multiple showcase steps together using a 'queue' concept. If there is currently a showcase being displayed, subsequent calls to Showcaser.showcase()
will add the new showcase step to an internal queue. Closing a showcase step using the 'next' button will cause the next showcase step to be popped off the queue and displayed to the user, until there are no more items left in the queue.
If you don't include the element
parameter, Showcaser will display a full-screen showcase instead.
Showcaser.showcase(text: string, element?: HTMLElement, options?: ShowcaseOptions): void
This will close the current step. If there is another step in the queue, it will be started.
Showcaser.close(): void
This will close the current step, and remove any queued showcases.
Showcaser.skipAll(): void
Showcaser.queueLength: number;
Field | Type | Default | Description |
---|---|---|---|
allowSkip |
boolean |
true |
Present the user with an option to skip all remaining showcase steps |
backgroundColor |
object |
See below | Configure the background color |
before |
function |
undefined |
Callback function that will be invoked just before this showcase step becomes visible |
buttonText |
string |
GOT IT |
Configure the next button text |
close |
function |
undefined |
Callback function that will be invoked after the user closes this showcase step |
fadeBackground |
boolean |
true |
Control the fade effect when the showcase appears |
paddingPx |
number |
15 |
Amount of padding around the element to showcase |
position |
object |
undefined |
Set the position of the text next to the element. See below |
positionTracker |
boolean |
false |
Track the element as it moves around the page, and re-draw the showcase |
scrollBufferPx |
number |
15 |
Set the amount of additional space to give the element when Showcaser scrolls to make the element visible on the page (helpful for clearing fixed positioned elements such as a header bar) |
skipText |
string |
Skip |
Configure the skip button text |
skip |
function |
undefined |
Callback function that will be invoked after the user clicks the skip button |
shape |
string |
circle |
Either circle or rectangle |
You can configure the background color of your showcase by using the backgroundColor
option on the ShowcaseOptions. The background color can be specified either using r, g, b
or hex
. The alpha channel (a
) is optional and defaults to 0.7
.
BackgroundColor (defaults to dark gray):
{
r?: number;
g?: number;
b?: number;
a?: number;
hex?: string;
}
Example:
Showcaser.showcase("I'm green!", element, {
backgroundColor: {
r: 0,
g: 132,
b: 10
}
});
Showcaser.showcase("I'm blue!", element, {
backgroundColor: {
hex: "#2196F3",
a: 0.5
}
});
By default, Showcaser will automatically position the text where there is room in the viewport. If you wish to manually control the positioning, you can use the position
option on the ShowcaseOptions.
Position:
{
horizontal: "right" | "center" | "left";
vertical: "top" | "middle" | "bottom";
}
Example
Showcaser.showcase("I'm on the left!", element, {
position: {
horizontal: "left",
vertical: "middle"
}
});