|
| 1 | +#Svelte ScrollSpy |
| 2 | + |
| 3 | +Svelte ScrollSpy is a[Svelte store](https://svelte.dev/docs/svelte-store) that |
| 4 | +tracks the intersecting state of a set of elements. The store provides a |
| 5 | +[Svelte action](https://svelte.dev/docs/svelte-action) that allows you to easily |
| 6 | +register any element for tracking. |
| 7 | + |
| 8 | +#Installation |
| 9 | + |
| 10 | +##NPM |
| 11 | + |
| 12 | +``` |
| 13 | +npm i -D svelte-scrollspy |
| 14 | +``` |
| 15 | + |
| 16 | +##Yarn |
| 17 | + |
| 18 | +``` |
| 19 | +yarn add -D svelte-scrollspy |
| 20 | +``` |
| 21 | + |
| 22 | +##bun |
| 23 | + |
| 24 | +``` |
| 25 | +bun i -d svelte-scrollspy |
| 26 | +``` |
| 27 | + |
| 28 | +#Why Svelte ScrollSpy? |
| 29 | + |
| 30 | +Although there are many intersection observer libraries out there, this library |
| 31 | +leverages the power of Svelte actions to provide a simple and intuitive API. |
| 32 | +Here are some of the benefits of using this library in a Svelte project. |
| 33 | + |
| 34 | +- Have a cleaner DOM without needing to add wrapper elements. |
| 35 | +- Easily register any elements, even nested elements, for tracking. |
| 36 | +- No need to worry about cleaning up when elements being tracked are removed |
| 37 | + from the DOM. Callbacks in Svelte action automatically do that. |
| 38 | + |
| 39 | +#API |
| 40 | + |
| 41 | +The object stored in the ScrollSpy store has the following properties: |
| 42 | + |
| 43 | +| Property| Description| |
| 44 | +| ------------------| ---------------------------------------------------------------------------------------------------------------------------------------------| |
| 45 | +|`amount`| The number of targets being spied on.| |
| 46 | +|`targets`| The ordered set of all targets being spied on, in the order of them being added as a target.| |
| 47 | +|`activeTargets`| The ordered set of all intersecting targets, in the order of entering intersection.| |
| 48 | +|`activeTarget`| The target that became active most recently and is still active. I.e. the last item in`activeTargets`.| |
| 49 | +|`lastActiveTarget`| The target that became active most recently. It may or may not be active now. If this target is no longer being spied on, this value is null.| |
| 50 | +|`activeId`| The id of`activeTarget`.| |
| 51 | +|`lastActiveId`| The id of`lastActiveTarget`.| |
| 52 | +|`isActive`| A function that checks if an element is active. Returns`null` if the given element is not a target being spied on.| |
| 53 | + |
| 54 | +The ScrollSpy store also has the following methods besides the`subscribe` |
| 55 | +method of a Svelte store. |
| 56 | + |
| 57 | +| Method| Description| |
| 58 | +| ----------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 59 | +|`spy`| A svelte action to add an element to the target list and start spying on it.| |
| 60 | +|`unspy`| Stop spying on a target and remove it from the target list. Accepts either the element itself or the id as the argument. This method is automatically called on all registered targets after they are removed from the DOM.| |
| 61 | +|`unspyAll`| Stop spying on all existing targets and remove them from the target list.| |
| 62 | + |
| 63 | +#Usage |
| 64 | + |
| 65 | +##Basic |
| 66 | + |
| 67 | +To use ScrollSpy to track the current section in view on the page. First create |
| 68 | +a scroll spy store with the imported`createScrollSpy` function. You can pass in |
| 69 | +an IntersectionObserverInit object to configure the IntersectionObserver used |
| 70 | +for tracking. |
| 71 | + |
| 72 | +In the example, we set the`rootMargin` to`-50% 0px` so that a section starts |
| 73 | +intersecting when it touches the vertical center of the viewport. |
| 74 | + |
| 75 | +```javascript |
| 76 | +importcreateScrollSpyfrom"svelte-scrollspy"; |
| 77 | +exportconstscrollSpy=createScrollSpy({ rootMargin:"-50% 0px" }); |
| 78 | +``` |
| 79 | + |
| 80 | +Then in any component file you can import the created store and use its`spy` |
| 81 | +method as a Svelte action to start spying on that element. |
| 82 | + |
| 83 | +```svelte |
| 84 | +<script> |
| 85 | + import scrollSpy from "$lib/stores/scroll-spy"; |
| 86 | +</script> |
| 87 | +
|
| 88 | +<section id="my-section" use:scrollSpy.spy><!-- ... --></section> |
| 89 | +<!-- Other sections... --> |
| 90 | +``` |
| 91 | + |
| 92 | +Element id is not required for spying. We gave an id to the element here only |
| 93 | +for scrolling with URL hash. Now, it is easy to make a navbar that highlights |
| 94 | +the current section. |
| 95 | + |
| 96 | +```svelte |
| 97 | +<script> |
| 98 | + import scrollSpy from "$lib/stores/scroll-spy"; |
| 99 | + import kebabCaseToCapWords from "$lib/utils.js"; |
| 100 | +</script> |
| 101 | +
|
| 102 | +<nav> |
| 103 | + <ul> |
| 104 | + {#each $scrollSpy.targets as section (section)} |
| 105 | + <li class={$scrollSpy.lastActiveTarget === section ? "active" : ""}> |
| 106 | + <a href={"#" + section.id}>{kebabCaseToCapWords(section.id)}</a> |
| 107 | + </li> |
| 108 | + {/each} |
| 109 | + </ul> |
| 110 | +</nav> |
| 111 | +
|
| 112 | +<style> |
| 113 | + /* Styling... */ |
| 114 | +</style> |
| 115 | +``` |
| 116 | + |
| 117 | +##Restricting What Can Be Spied On |
| 118 | + |
| 119 | +You can augment Scroll Spy with additional properties and methods. For example, |
| 120 | +we can enforce that all elements being spied on must have an ID, and we can |
| 121 | +assign an arbitrary label to each element when they are registered. |
| 122 | + |
| 123 | +To do this, we create our custom Svelte store by extending the functionality of |
| 124 | +Scroll Spy. |
| 125 | + |
| 126 | +```javascript |
| 127 | +importcreateScrollSpyfrom'svelte-scrollspy'; |
| 128 | +importtype {ActionReturn }from'svelte/action'; |
| 129 | + |
| 130 | +exportconstsectionSpy= (()=> { |
| 131 | +// use spy store's functionality |
| 132 | +constspy=createScrollSpy({ rootMargin:'-50% 0px' }); |
| 133 | + |
| 134 | +return { |
| 135 | +...spy, |
| 136 | + |
| 137 | +// Overwrite spy() to add restriction on targets and apply custom attribute |
| 138 | + |
| 139 | +/** |
| 140 | + * A svelte action to register an element as a section to spy on. The |
| 141 | + * element must have an id. |
| 142 | + * |
| 143 | + *@param [label] - an arbitrary label for the section. This action assigns |
| 144 | + * the label value to the element's `data-section-label` attribute. If no |
| 145 | + * label is given, the element's id is transformed into a capitalized |
| 146 | + * string and used as the label. |
| 147 | +*/ |
| 148 | +spy( |
| 149 | + target: string|Element, |
| 150 | + label?: string, |
| 151 | + ): ActionReturn<string, { id: string }> { |
| 152 | +constelem= |
| 153 | + targetinstanceofElement? target:document.getElementById(target); |
| 154 | + |
| 155 | +if (!elem||!elem.id)return {}; |
| 156 | + |
| 157 | + label??=elem.id// kebab-case to Capitalized Words |
| 158 | + .replace(/-./g, (m)=>""+ m[1].toUpperCase()) |
| 159 | + .replace(/^(.)/, (m)=>m.toUpperCase()); |
| 160 | + |
| 161 | +const {destroy }=spy.spy(elem); |
| 162 | +if (destroy)elem.setAttribute("data-section-label", label); |
| 163 | +return { destroy }; |
| 164 | + }, |
| 165 | + }; |
| 166 | +})(); |
| 167 | +``` |
| 168 | +
|
| 169 | +We can then use our custom store to assign labels with Svelte action syntax. |
| 170 | +
|
| 171 | +```svelte |
| 172 | +<section id="my-section" use:sectionSpy.spy={"My Label"}><!--...--></section> |
| 173 | +<!-- Other sections...--> |
| 174 | +<footer>You're at the section: {$sectionSpy.activeLabel}</footer> |
| 175 | +``` |
| 176 | +
|
| 177 | +## Adding Custom Properties to the Store |
| 178 | +
|
| 179 | +You can even add custom properties to the store. |
| 180 | +
|
| 181 | +```typescript |
| 182 | +export const sectionSpy = (() => { |
| 183 | + const spy = createSpy({ rootMargin: "-50% 0px" }); |
| 184 | +
|
| 185 | + // extend spy store's properties |
| 186 | +interface SectionSpyextends Spy { |
| 187 | +/** The label of the active target (attribute: "data-section-label")*/ |
| 188 | + activeLabel: string|null; |
| 189 | + |
| 190 | +/** |
| 191 | + * The label of the last active section (attribute: "data-section-label") |
| 192 | +*/ |
| 193 | + lastActiveLabel: string|null; |
| 194 | + } |
| 195 | + |
| 196 | +functiongetSectionSpy(): SectionSpy { |
| 197 | +return { |
| 198 | +...get(spy), |
| 199 | +getactiveLabel() { |
| 200 | +returnthis.activeTarget?.getAttribute("data-section-label")??null; |
| 201 | + }, |
| 202 | +getlastActiveLabel() { |
| 203 | +return ( |
| 204 | +this.lastActiveTarget?.getAttribute("data-section-label")??null |
| 205 | + ); |
| 206 | + }, |
| 207 | + }; |
| 208 | + } |
| 209 | + |
| 210 | +// Create our own custom store |
| 211 | +const {subscribe,set }= writable<SectionSpy>(getSectionSpy()); |
| 212 | +// Update our custom store whenever the spy store updates |
| 213 | +spy.subscribe(()=>set(getSectionSpy())); |
| 214 | + |
| 215 | +return { |
| 216 | +...spy, |
| 217 | + subscribe, |
| 218 | + |
| 219 | +// Implement our own spy() method to add restriction on spied targets and |
| 220 | +// add custom attribute to the targets |
| 221 | +spy( |
| 222 | + target: string|Element, |
| 223 | + label?: string, |
| 224 | + ): ActionReturn<string, { id: string }> { |
| 225 | +constelem= |
| 226 | + targetinstanceofElement? target:document.getElementById(target); |
| 227 | + |
| 228 | +if (!elem||!elem.id)return {}; |
| 229 | + |
| 230 | + label??=elem.id// kebab-case to Capitalized Words |
| 231 | + .replace(/-./g, (m)=>""+ m[1].toUpperCase()) |
| 232 | + .replace(/^(.)/, (m)=>m.toUpperCase()); |
| 233 | + |
| 234 | +const {destroy }=spy.spy(elem); |
| 235 | +if (destroy)elem.setAttribute("data-section-label", label); |
| 236 | +return { destroy }; |
| 237 | + }, |
| 238 | + }; |
| 239 | +})(); |
| 240 | +``` |
| 241 | +
|
| 242 | +# License |
| 243 | +
|
| 244 | +[MIT](./LICENSE) |