# Feature Hints

> Add pulsing hint beacons to your UI with Driver.js. Users click a beacon to open a popover explaining the feature. Style the beacons and popovers to match your product.

Hints are pulsing beacons that sit on the page. The user clicks one to open a popover, in any order. Nothing is blocked, so the page stays usable.

They are a separate entry with their own stylesheet. You don't need `driver.css` unless you also use tours.

```js
import { hints } from "driver.js/hints";
import "driver.js/dist/hints.css";
```

Each hint points at an element and describes it in a popover. The demo also turns on the optional overlay.

```js
const productHints = hints({
  overlay: true,
  overlayOpacity: 0.5,
  hints: [
    {
      element: "#export-btn",
      id: "export",
      popover: {
        title: "Export your data",
        description: "Download this report as CSV or PDF.",
      },
    },
    {
      element: "#summary",
      id: "summary",
      beacon: { side: "left", align: "center" },
      popover: {
        title: "Auto-generated summary",
        description: "Written for you from the quarter's numbers.",
        side: "bottom",
      },
    },
  ],
});

productHints.show();
```

## Closing vs. dismissing

- Closing keeps the beacon. Clicking the beacon again, clicking outside or pressing <kbd>Escape</kbd> closes the popover, and the hint can be opened again.
- Dismissing removes the beacon. The _Got it_ button does it and runs `onDismiss`. Set `onButtonClick` to decide yourself what the button does.

Only one hint is open at a time.

## Remembering dismissals

Dismissals last until the page reloads. To keep them, give hints an `id` and save it in `onDismiss`. Dismiss a hint below, then load the page again.

```js
const saved = JSON.parse(localStorage.getItem("hints") ?? "[]");
const dismissed = new Set(saved);

const productHints = hints({
  hints: allHints.filter(hint => !dismissed.has(hint.id)),
  onDismiss: (element, hint) => {
    dismissed.add(hint.id);
    localStorage.setItem("hints", JSON.stringify([...dismissed]));
  },
});

productHints.show();
```

## Dimming the page

`overlay: true` dims the page while a hint is open, like a tour step. The element is cut out and stays usable, the popover points at the element instead of the beacon, and a click on the dimmed page closes the hint.

```js
const productHints = hints({
  overlay: true,
  overlayColor: "#000",
  overlayOpacity: 0.5,
  hints: [
    // ...
  ],
});
```

## Using hints alongside a tour

While a tour runs, the beacons hide. They come back when it ends. A hint can also start a tour from its button. Open the beacon below and take the tour.

```js
const tour = driver({
  steps: [
    // ...
  ],
});

const productHints = hints({
  hints: [
    {
      element: "#whats-new",
      id: "whats-new",
      popover: {
        title: "New dashboard",
        description: "Want a quick walkthrough?",
        buttonText: "Take the tour",
        onButtonClick: (element, hint, { hints: instance }) => {
          instance.close();
          tour.drive();
        },
      },
    },
  ],
});
```

For more buttons or your own markup, use `onPopoverRender`, like in [tours](https://driverjs.com/docs/custom-buttons.md).

## Styling

### Beacon placement

A beacon sits on an edge of its element: `side` picks the edge and `align` the position along it. The default is the top right corner. `offsetX` and `offsetY` move it by a number of pixels, where positive is right and down.

```js
const productHints = hints({
  hints: [
    {
      element: "#dashboard",
      beacon: { side: "top", align: "end", offsetX: -12, offsetY: 8 },
      popover: { title: "Dashboard" },
    },
  ],
});
```

### Beacon color and size

Beacons read CSS variables for their color and size. Set them on `.driver-hint` for all beacons, or on a class you give one beacon with `className`. All beacon variables and classes are in [Theming](https://driverjs.com/docs/theming.md#hints).

```css
/* All beacons */
.driver-hint {
  --driver-hint-color: #e11d48;
  --driver-hint-size: 28px;
}

/* Only beacons carrying a class */
.my-special-hint {
  --driver-hint-color: #059669;
}
```

```js
const productHints = hints({
  hints: [
    {
      element: "#export-btn",
      beacon: { className: "my-special-hint" },
      popover: { title: "A green beacon" },
    },
  ],
});
```

### Static beacons

`animate: false` turns the pulse off. Users who prefer reduced motion never see it.

```js
const productHints = hints({
  // For every hint. A hint's own beacon values win.
  beacon: { animate: false },
  hints: [
    // ...
  ],
});
```

### Custom button text

`buttonText` changes the _Got it_ button, for all hints or in one hint's `popover`. `showButton: false` hides it, for hints you dismiss from code.

```js
const productHints = hints({
  buttonText: "Thanks, understood",
  hints: [
    {
      element: "#share-btn",
      popover: {
        title: "No button at all",
        showButton: false,
      },
    },
  ],
});
```

### Theming the popover

Hint popovers are regular popovers, so `popoverClass` and everything in [Theming](https://driverjs.com/docs/theming.md#popover) apply.

```js
const productHints = hints({
  popoverClass: "driverjs-theme",
  hints: [
    // ...
  ],
});
```

## Reference

- Every option: [Hints Configuration](https://driverjs.com/docs/configuration.md#hints-configuration)
- Every method: [API Reference](https://driverjs.com/docs/api.md#hints)
