https://github.com/nani-samireddy/cue.js
A lightweight, flexible, and beautifully designed JavaScript library for interactive product tours and feature walkthroughs. Guide your users with elegance and simplicity.
https://github.com/nani-samireddy/cue.js
js js-library npm-package
Last synced: about 1 year ago
JSON representation
A lightweight, flexible, and beautifully designed JavaScript library for interactive product tours and feature walkthroughs. Guide your users with elegance and simplicity.
- Host: GitHub
- URL: https://github.com/nani-samireddy/cue.js
- Owner: nani-samireddy
- License: mit
- Created: 2025-05-22T14:34:52.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-22T17:18:43.000Z (about 1 year ago)
- Last Synced: 2025-06-28T16:09:59.305Z (about 1 year ago)
- Topics: js, js-library, npm-package
- Language: JavaScript
- Homepage: https://cue-js.gitbook.io/docs
- Size: 1010 KB
- Stars: 4
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: readme.MD
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# @nani_samireddy/cue.js
[](https://www.npmjs.com/package/@nani_samireddy/cue.js)
[](https://www.npmjs.com/package/@nani_samireddy/cue.js)
[](https://opensource.org/licenses/MIT)
[](https://github.com/nani-samireddy/cue.js/stargazers)
A lightweight, flexible, and beautifully designed JavaScript library for interactive product tours and feature walkthroughs. Guide your users with elegance and simplicity.
## ✨ Features
* **Lightweight & No Dependencies:** Built with vanilla JavaScript, keeping your bundle size small.
* **Declarative API:** Define your tours with simple, readable step configurations.
* **Smart Positioning:** Tooltips intelligently adjust to stay within the viewport.
* **Dynamic Content Support:** Guide users through elements that appear or change dynamically.
* **Customizable:** Easily extendable with custom styling, callbacks, and element targeting.
* **Event Hooks:** Integrate with analytics or trigger custom actions at various tour lifecycle points.
* **Keyboard Navigation:** Accessible tour controls for a better user experience.
Learn more about the features and how to use them in the [documentation](https://cue-js.gitbook.io/docs).
## 📦 Table of Contents
- [@nani\_samireddy/cue.js](#nani_samireddycuejs)
- [✨ Features](#-features)
- [📦 Table of Contents](#-table-of-contents)
- [🚀 Installation](#-installation)
- [npm](#npm)
- [Yarn](#yarn)
- [CDN](#cdn)
- [💡 Usage](#-usage)
- [HTML Structure](#html-structure)
- [JavaScript](#javascript)
- [🎨 Styling](#-styling)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)
---
## 🚀 Installation
### npm
Install the package using npm:
```bash
npm install @nani_samireddy/cue.js
````
### Yarn
Install the package using Yarn:
```bash
yarn add @nani_samireddy/cue.js
```
### CDN
You can quickly include Cue.js in your project using a CDN (Content Delivery Network).
**Minified Version (Recommended for Production):**
```html
```
**Unminified Version (For Development/Debugging):**
```html
```
*Note: Replace `1.0.0` with the latest version number available on npm/CDN.*
-----
## 💡 Usage
### HTML Structure
Ensure your HTML elements have unique IDs or accessible CSS classes for `Cue.js` to target.
```html
Start Guided Tour
...
...
```
### JavaScript
If you're using a module bundler (like Webpack, Vite, Parcel), import `Cue` like this:
```javascript
import Cue from '@nani_samireddy/cue.js';
// Also import the CSS. How this works depends on your bundler's configuration.
// Common ways:
// import '@nani_samireddy/cue.js/dist/cue.css'; // Or cue.min.css
// import '@nani_samireddy/cue.js/style.css'; // If you've configured your bundler to look in src/ for 'style.css'
```
If you're using the **CDN version** or **vanilla JavaScript**, `Cue` will be globally available as `window.Cue`.
```javascript
document.addEventListener('DOMContentLoaded', () => {
// Initialize Cue.js
const cue = new Cue({
// Global options (optional)
overlay: true, // Show dimmed overlay (default: true)
showProgress: true, // Show "Step X of Y" (default: false)
showBullets: true, // Show navigation dots (default: false)
nextLabel: 'Continue', // Custom button text
debug: true // Enable console logging for development
});
const tourSteps = [
{
target: '#my-first-feature', // Required: CSS selector or DOM element
title: 'Welcome!',
content: 'This is the first feature you should explore.',
position: 'bottom' // Optional: 'top', 'bottom', 'left', 'right', 'center', 'auto'
},
{
target: '.important-setting',
title: 'Important Settings',
content: 'Don\'t forget to customize your preferences here.',
position: 'left',
// Step-specific option overrides
showButtons: false, // Hide default buttons for this step
preStep: () => {
console.log('Preparing for the settings step...');
// You can show/hide elements or fetch data here.
},
postStep: () => {
console.log('Finished settings step.');
}
},
{
target: '#start-tour-button',
title: 'That\'s it!',
content: 'You\'re ready to start exploring. Click "Done" to finish the tour.',
position: 'top'
}
];
cue.setSteps(tourSteps);
// Start the tour when a button is clicked
document.getElementById('start-tour-button').addEventListener('click', () => {
cue.start();
});
// --- Event Hooks (Optional) ---
cue.onStart(() => {
console.log('Tour started!');
});
cue.onChange((stepData, currentIndex) => {
console.log(`Moved to step ${currentIndex + 1}: ${stepData.title}`);
// Integrate with analytics: `trackEvent('Cue.js Tour Step', { step: currentIndex + 1, title: stepData.title });`
});
cue.onComplete(() => {
console.log('Tour completed! 🎉');
// Redirect, show a success message, etc.
});
cue.onExit((currentStepIndex) => {
console.log(`Tour exited at step ${currentStepIndex + 1}.`);
});
});
```
-----
## 🎨 Styling
Cue.js comes with beautiful, modern default styles. You can easily customize the look and feel using CSS variables:
```css
/* Custom styles in your own CSS file */
:root {
--cue-primary-color: #6a0dad; /* Deep Purple */
--cue-accent-color: #ff6f00; /* Orange Accent */
--cue-bg-color: #f0f8ff; /* Alice Blue background */
--cue-border-radius: 12px; /* More rounded corners */
--cue-shadow-lg: 0 15px 25px rgba(0, 0, 0, 0.15); /* Stronger shadow */
}
/* You can also override specific classes */
.custom-cta-tooltip {
background-color: #4CAF50;
color: white;
border: none;
font-weight: bold;
}
.custom-cta-tooltip .cue-tooltip-title {
color: white;
}
.custom-cta-tooltip::before {
border-color: #4CAF50 transparent transparent transparent !important;
}
```
-----
## 🤝 Contributing
We welcome contributions to Cue.js\! Please see our [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.
-----
## 📄 License
Cue.js is [MIT licensed](./LICENSE).