Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/9am/use-spotlight
A react hook that generates an animated 'spotlight' follows the active target. đ
https://github.com/9am/use-spotlight
active animation highlight hooks react spotlight target
Last synced: 11 days ago
JSON representation
A react hook that generates an animated 'spotlight' follows the active target. đ
- Host: GitHub
- URL: https://github.com/9am/use-spotlight
- Owner: 9am
- License: mit
- Created: 2023-11-06T09:36:47.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-01-11T06:28:09.000Z (10 months ago)
- Last Synced: 2024-10-13T20:17:04.062Z (about 1 month ago)
- Topics: active, animation, highlight, hooks, react, spotlight, target
- Language: TypeScript
- Homepage:
- Size: 192 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
use-spotlight
A react hook that generates an animated 'spotlight' follows the active target. đ
## Features
- đĻ Generate a 'spotlight' that **follows the size and position** of any active target.
- đ **Auto-updated** after resizing or DOM changing.
- âĄī¸ Options to fit any position between **smooth effect** to **high-efficiency performance**.
- đĒŠ Apply **customized style** to the 'light' easily.
- đŊ **â 2kB** minzipped.
## Demo
https://github.com/9am/use-spotlight/assets/1435457/5b570780-abb7-4df9-9e19-7454eafecce4
### Live demos
|Description|Live demo|
|:---------:|:-------:|
| **Basic** | [](https://codesandbox.io/s/basic-dfpl4w?fontsize=14&hidenavigation=1&module=%2Fsrc%2FtoggleButton.tsx&theme=dark) |
| **Auto-updated resize** | [](https://codesandbox.io/s/auto-follow-resize-8grssc?fontsize=14&hidenavigation=1&module=%2Fsrc%2FtoggleButton.tsx&theme=dark) |
| **Auto-updated DOM change** | [](https://codesandbox.io/s/auto-follow-mutation-jjlx8h?fontsize=14&hidenavigation=1&module=%2Fsrc%2FtoggleButton.tsx&theme=dark) |
| **Throttle** | [](https://codesandbox.io/s/throttle-tpt53s?fontsize=14&hidenavigation=1&module=%2Fsrc%2FtoggleButton.tsx&theme=dark) |
| **Custom light style** | [](https://codesandbox.io/s/custom-style-v6pwq3?fontsize=14&hidenavigation=1&module=%2Fsrc%2FtoggleButton.tsx&theme=dark) |
| **Pseudo light** | [](https://codesandbox.io/s/pseudo-pj7zdn?fontsize=14&hidenavigation=1&module=%2Fsrc%2FtoggleButton.tsx&theme=dark) |
### Use cases
> [!NOTE]
>
> - An animated active indicator for a component like ``, ``.
> - A highlight effect for a self-controlled focused system, like the result list of a ``.
> - ...
## Usage
#### Install
```sh
npm install use-spotlight
```
#### JSX
```diff
+import { useSpotlight } from 'use-spotlight'
() => {
const [active, setActive] = useState(-1)
// init hook
+ const { stage, actor, style } = useSpotlight()
return (
// set ref for 'stage'
- setActive(val)}
// set ref for 'actor'
+ ref={val === active ? actor : null}
>
{val}
{list.map(({ val }) => (
))}
// set 'style' to the light
+
)
}
```
## Documentation
### `useSpotlight( SpotlightOptions? )`
#### Parameters: [`SpotlightOptions`](https://github.com/9am/use-spotlight/blob/main/src/types.ts#L12)
- **`throttleWait`**: The number of milliseconds to throttle invocations to. `default: 0`
- **`stageBorderEdge`**: With default setting, the 'light' will be positioned relative to the *padding edge* of the 'stage', which will cause an offset if 'stage' has *borders*. Set to `true`, if want to use the *border edge*, which will hurt performance but be more accurate on the position. `default: false`
- **`stageMutation`**: Enable watching 'stage' `childlist` `subtree` DOM mutation. `default: false`
- **`lightPseudo`**: `::before` or `::after` to enable pseudo element as 'light'. In this mode, there's no need to insert a 'light' element explicitly. It's useful for case that no extra element wanted under the 'stage'. `default: null`
#### Returns: [`Spotlight`](https://github.com/9am/use-spotlight/blob/main/src/types.ts#L24)
- **`stage`**: The RefCallback which will be assigned to node as container.
- **`actor`**: The RefCallback which will be assigned to node as target to follow.
- **`style`**: The CSSProperties for the node 'light'.
- **`size`**: The offset `[x, y, width, height]` between 'actor' and 'stage'.
> [!IMPORTANT]
>
> - **`stageBorderEdge=true`** uses `getComputedStyle()` to calculate the `border` size of 'stage', but it's bad for performance, there're other alternatives to achieve this:
> 1. Use `outline` instead of `border`.
> 2. Override the style of 'light': `top: -1 * var(--border-top-size-stage)`, `left: -1 * var(--border-left-size-stage)`
> - **`stageMutation=true`** add an extra `MutationObserver` to the 'stage', consider using the default setting unless it can not cover some of the cases.
## License
[MIT](LICENSE)