Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/smastrom/vue-use-fixed-header
🔥 Turn your boring fixed header into a smart one with three lines of code.
https://github.com/smastrom/vue-use-fixed-header
fixed-header nuxt nuxt-3 use-fixed-header vue vue-3 vue-composable
Last synced: 16 days ago
JSON representation
🔥 Turn your boring fixed header into a smart one with three lines of code.
- Host: GitHub
- URL: https://github.com/smastrom/vue-use-fixed-header
- Owner: smastrom
- License: mit
- Created: 2023-07-10T17:31:12.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-02-05T19:02:59.000Z (10 months ago)
- Last Synced: 2024-10-19T07:08:42.543Z (29 days ago)
- Topics: fixed-header, nuxt, nuxt-3, use-fixed-header, vue, vue-3, vue-composable
- Language: TypeScript
- Homepage: https://vue-use-fixed-header.pages.dev
- Size: 199 KB
- Stars: 57
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
   
# Vue Use Fixed Header
Turn your boring fixed header into a smart one with three lines of code.
**Demo:** [Website](https://vue-use-fixed-header.pages.dev/) — **Examples:** [Vue 3](https://stackblitz.com/edit/vitejs-vite-nc7ey2?file=index.html,src%2Fcomponents%2FPage.vue) - [Nuxt 3](https://stackblitz.com/edit/nuxt-starter-zbtjes?file=layouts%2Fdefault.vue)
## Features
- **Dead simple** - Write three lines of code and you're ready to go
- **Enjoyable** - When scrolling down, the header is hidden, when scrolling up, the header is shown.
- **Smart** - Behaves as expected on page load, hovering, dropdown navigation, top-reached and reduced motion.
- **Dynamic** - Functionalities are automatically enabled/disabled if your header turns from fixed/sticky to something else or it is hidden at different viewports
- **Flexible** - Works with any scrolling container
## Installation
```bash
pnpm add vue-use-fixed-header
```
```bash
yarn add vue-use-fixed-header
```
```bash
npm i vue-use-fixed-header
```
## Usage
Pass your header's template ref to `useFixedHeader`. Then apply the returned reactive styles. That's it.
```vue
import { ref } from 'vue'
import { useFixedHeader } from 'vue-use-fixed-header'
const headerRef = ref(null)
const { styles } = useFixedHeader(headerRef)
.Header {
position: fixed; /* or sticky */
top: 0;
/* Other styles... */
}
```
All you have to do is to set `position: fixed` (or `sticky`) to your header. `useFixedHeader` will take care of the rest.
## Automatic behavior toggling
On resize, `useFixedHeader` checks your header's `position` and `display` properties to determine whether its functionalities should be enabled or not.
_Disabled_ means that no event listeners are attached and the returned styles match an empty object `{}`.
### Media queries
Hence feel free to have code like this, it will just work as expected:
```css
.Header {
position: fixed;
}
/* Will be disabled */
@media (max-width: 768px) {
.Header {
position: relative;
}
}
/* Same */
@media (max-width: 375px) {
.Header {
display: none;
}
}
```
### Advanced scenarios
Let's suppose your header in some pages is not fixed/sticky and you're using some reactive logic to determine whether it should be or not.
You can pass a signal to the `watch` property of `useFixedHeader` to perform a check everytime the value changes:
```vue
const route = useRoute()
const headerRef = ref(null)
const isPricingPage = computed(() => route.name === 'Pricing')
const { styles } = useFixedHeader(headerRef, {
watch: isPricingPage, // Will perform a check everytime the value changes
})
```
`useFixedHeader` will automatically toggle functionalities when navigating to/from the _Pricing_ page.
> You can pass either a `ref` or a `computed` (without `.value`).
## API
```ts
declare function useFixedHeader(
target: Ref | HTMLElement | null
options?: UseFixedHeaderOptions
): {
styles: Readonly>
isEnter: ComputedRef
isLeave: ComputedRef
}
interface UseFixedHeaderOptions {
/**
* Scrolling container. Matches `document.documentElement` if `null`.
*
* @default null
*/
root: Ref | HTMLElement | null
/**
* Signal without `.value` (ref or computed) to be watched
* for automatic behavior toggling.
*
* @default null
*/
watch: Ref | ComputedRef
/**
* Whether to transition `opacity` property from 0 to 1
* and vice versa along with the `transform` property
*
* @default false
*/
transitionOpacity: boolean | Ref | ComputedRef
}
```
## License
MIT Licensed - Simone Mastromattei © 2023