https://github.com/edward-shen/MMM-page-indicator
MagicMirror² module to display what page you're on.
https://github.com/edward-shen/MMM-page-indicator
indicator magicmirror pagination
Last synced: 6 months ago
JSON representation
MagicMirror² module to display what page you're on.
- Host: GitHub
- URL: https://github.com/edward-shen/MMM-page-indicator
- Owner: edward-shen
- License: mit
- Created: 2017-06-14T20:10:41.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2025-10-17T21:44:10.000Z (8 months ago)
- Last Synced: 2025-10-18T23:13:00.974Z (8 months ago)
- Topics: indicator, magicmirror, pagination
- Language: JavaScript
- Size: 939 KB
- Stars: 51
- Watchers: 5
- Forks: 14
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-mmm - **MMM-Page-Indicator**
README
# MMM-page-indicator
**MMM-page-indicator** is a [MagicMirror²][mm] module that indicates which page is currently visible. It serves as an indicator and provides an easy way to switch pages by clicking on the circle representing the page you want to navigate to.
This module works well with [MMM-pages], but it is compatible with any module that sends the `PAGE_CHANGED` notification.
## Screenshot
## Project Status
This module is in **maintenance mode**. It is a small but mature and does what it is supposed to do.
We will be keeping this module compatible with the latest version of MagicMirror², but we don't plan to add any new features or make any major changes to the codebase.
If you have any issues or bugs, please feel free to open an issue.
## Installation
In your terminal, go to your MagicMirror's module directory and clone this repository:
```bash
cd ~/MagicMirror/modules
git clone https://github.com/edward-shen/MMM-page-indicator
```
### Update
Just enter the module's directory, pull the update and install the dependencies:
```bash
cd ~/MagicMirror/modules/MMM-page-indicator
git pull
```
## Configuration
To use this module, add it to the modules array in the `config/config.js` file:
```js
{
module: 'MMM-page-indicator',
position: 'bottom_bar',
config: {
activeBright: true,
}
},
```
### Configuration options
All configuration options are optional.
| Option | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `pages` | Number of pages that you have.
**Value type:** `int`
**Default value:** `3` |
| `activeBright` | Should the active circle be bright.
**Value type:** `boolean`
**Default value:** `false` |
| `inactiveDimmed` | Should the inactive circles be dimmed?
**Value type:** `boolean`
**Default value:** `true` |
| `inactiveHollow` | Should the inactive circles be hollow?
**Value type:** `boolean`
**Default value:** `true` |
| `showPageNumberOnHover` | Should the page number be shown on hover?
**Value type:** `boolean`
**Default value:** `true` |
## Styling
With the CSS classes `active-page` and `page-{i}` you can easily style the page indicators. The `active-page` class is applied to the currently active page indicator, while the `page-{i}` class is applied to the page indicator of page number `i`. This allows you to change the color, icon and other properties of the indicators.
Without styling, the indicators will look like this:
Below are some styling examples. Just add them to your `custom.css` file (usually located in `~/MagicMirror/css/`) to test them on your system. With CSS you can do a lot of things, so feel free to experiment with the styles.
### Example: Changing the icon of a page indicator
You can assign a different icon per page indicator. This example sets the page 2 indicator to a orange star.
Click to see the CSS
```css
.MMM-page-indicator .page-2::before {
color: orange;
content: "⭐";
}
```
### Example: Animating the active page indicator
This example extends the one above and adds a pulsing effect to the active page indicator.
Click to see the CSS
```css
.MMM-page-indicator .page-2::before {
color: orange;
content: "⭐";
}
@keyframes pulse {
0%,
100% {
transform: scale(1);
opacity: 1;
}
50% {
transform: scale(1.3);
opacity: 0.6;
}
}
.MMM-page-indicator .active-page {
animation: pulse 1.2s ease-in-out infinite;
}
```
### Example: Adding description text to the page indicators
This is an advanced example which adds a description text to the page indicators and changes every indicator to a different icon.
Click to see the CSS
```css
.MMM-page-indicator .indicator::before {
font-size: 1.5rem;
font-weight: 600;
font-variant-emoji: text;
line-height: 1.6;
letter-spacing: 0.2rem;
white-space: pre;
padding: 0px 15px;
}
.MMM-page-indicator .page-0::before {
content: "🏠 \A Home";
}
.MMM-page-indicator .page-1::before {
content: "📅 \A Calendar";
}
.MMM-page-indicator .page-2::before {
content: "⭐ \A News";
}
.MMM-page-indicator .page-3::before {
content: "⛅ \A Weather";
}
@keyframes pulse {
0%,
100% {
transform: scale(1);
opacity: 1;
}
50% {
transform: scale(1.3);
opacity: 0.6;
}
}
.MMM-page-indicator .active-page {
color: orange;
font-variant-emoji: text;
animation: pulse 5s ease-in-out infinite;
}
```
### Example: Rectangular progress-style indicators
Turn the dots into elongated bars with a sweeping highlight similar to carousel indicators. The active bar turns red and shows a yellow streak sliding across it.
Click to see the CSS
```css
.MMM-page-indicator {
--indicator-width: 80px;
--indicator-height: 4px;
--indicator-streak-width: 8px;
--indicator-gap: 8px;
--indicator-color: #e1e2e4;
--indicator-active-color: #e40000;
--indicator-streak-color: yellow;
--indicator-streak-blur: 2px;
--indicator-sweep-duration: 5s;
}
.MMM-page-indicator .circle-wrapper {
margin: 0 var(--indicator-gap);
}
.MMM-page-indicator .indicator {
display: inline-block;
width: var(--indicator-width);
height: var(--indicator-height);
border-radius: 2px;
background: var(--indicator-color);
position: relative;
overflow: hidden;
color: transparent;
}
.MMM-page-indicator .indicator::before {
content: "";
}
.MMM-page-indicator .active-page {
background: var(--indicator-active-color);
}
.MMM-page-indicator .active-page::after {
content: "";
position: absolute;
top: -150%;
bottom: -150%;
left: calc(var(--indicator-streak-width) * -2);
width: var(--indicator-streak-width);
background: var(--indicator-streak-color);
filter: blur(var(--indicator-streak-blur));
opacity: 0.9;
animation: indicator-sweep var(--indicator-sweep-duration) linear infinite;
pointer-events: none;
}
@keyframes indicator-sweep {
0% {
transform: translateX(0);
}
100% {
transform: translateX(
calc(var(--indicator-width) + (var(--indicator-streak-width) * 2))
);
}
}
```
## Sending notifications to the module
This module responds to the notification `PAGE_CHANGED`. The payload should be an `integer`. Note that this has strict error checking, so `"3"` will not work, while `3` will. Also do note that to switch to page 1, you need to send `0` to the module. **This uses a zero-based numbering system.**
Let's say that you want to change the indicator to page 3. In your code, you would write:
```js
this.sendNotification("PAGE_CHANGED", 2);
```
This would cause the module to change show that you are on page 3.
If you wish to change the number of pages, you need to send a `MAX_PAGES_CHANGED` notification with your payload as an integer.
```js
this.sendNotification("MAX_PAGES_CHANGED", 4);
```
This would now show that there are now 4 pages to display.
You can also just send `PAGE_INCREMENT` or `PAGE_DECREMENT` without any payloads to have the module change the displayed page by one. If you are using [MMM-pages] with this module, sending an integer as a payload for a `PAGE_INCREMENT` or `PAGE_DECREMENT` notification will perform as described in [the MMM-pages documentation](https://github.com/edward-shen/MMM-pages#notifications). If you are not using MMM-pages, the indicator will ignore the payload and just change the displayed page by one.
## FAQ
- Help! My module is (above/below) another module in the same region but I want it to be somewhere else!
The order of your `config.js` determines your module location. If you have two modules, both with `position:bottom_bar`, the one that is first listed will appear on top. The rest will appear in the same order you defined them in. If you want this module to be at the very bottom, define this module as the last module in your `config.js` file. If you want it to be on top in that region, make sure no other module is defined before it that has the same region.
- Can I make a pull request?
Please do! I'd love for this to be integrated in many modules!
- I want more config options!
Please make an issue. Thanks!
## Developer commands
- `npm install` - Install dependencies for development.
- `node --run lint` - Run linting checks.
- `node --run lint:fix` - Fix linting issues.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.
## Changelog
All notable changes to this project will be documented in the [CHANGELOG](CHANGELOG.md) file.
[mm]: https://github.com/MagicMirrorOrg/MagicMirror
[MMM-pages]: https://github.com/edward-shen/MMM-pages