@hettiger/ngx-fragment-link-faker
v0.1.3
Published
Mimics default browser behavior of fragment links in Angular applications.
Downloads
10
Maintainers
Readme
NgxFragmentLinkFaker
Mimics default browser behavior of fragment links in Angular applications.
Allows applying changes in a scoped manner using a simple directive.
Supports smooth scroll behavior.
This library was generated with Angular CLI version 13.0.0.
Example use case
E.g. you have existing HTML content with a table of contents:
<h2>Table of contents</h2>
<ul>
<li><a href="#some-headline">Some Headline</a></li>
<li><a href="#another-headline">Another Headline</a></li>
</ul>
<article>
<h2 id="some-headline">Some Headline</h2>
<p>
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
</p>
</article>
<article>
<h2>
<a name="another-headline"></a>
Another Headline
</h2>
<p>
Lorem ipsum dolor sit amet, consectetur adipisicing elit.
</p>
</article>
This table of contents does not work as expected in an Angular app.
Clicking one of the links would not adjust the scroll position.
Instead you'd trigger a navigation to the homepage.
Usually the solution requires manual changes to the original HTML content.
Also you'd typically need to handle click events or fragment changes somehow.
Probably you want a nice smooth scroll effect that works in all major browser.
This library gets the job done without changing any of the existing HTML contents.
Setup
npm i @hettiger/ngx-fragment-link-faker --save
- Import the
FragmentLinkFakerModule
module
import { FragmentLinkFakerModule } from '@hettiger/ngx-fragment-link-faker';
@NgModule({
imports: [
// …
FragmentLinkFakerModule,
],
// …
})
// …
Usage
Simply add the mhFakeFragmentLinks
directive to a wrapper element in your template.
In case you need to account for e.g. a fixed navbar simply provide a delta in px.
Example: <main mhFakeFragmentLinks [mhScrollTopDelta]="64"> … </main>
You might as well configure the scroll behavior to enable smooth scrolling:
Example: <main mhFakeFragmentLinks mhScrollBehavior="smooth"> … </main>
Smooth scroll behavior is not supported in all browsers at the time of writing.
However, you may simply add a polyfill for now:
npm i seamless-scroll-polyfill --save
// src/polyfills.ts import { polyfill as polyfillSeamlessScroll } from "seamless-scroll-polyfill"; polyfillSeamlessScroll();
Brief example
<main mhFakeFragmentLinks [mhScrollTopDelta]="20" mhScrollBehavior="smooth">
<h2>Table of contents</h2>
<ul>
<li>
<a href="#some-headline">Some Headline</a>
<a href="#another-headline">Another Headline</a>
</li>
</ul>
<!-- … -->
</main>
Router Extra Options
Anchor scrolling may not work when you enable scrollPositionRestoration
on the RouterModule
.
Make sure to also enable the anchorScrolling
option and set an appropriate scrollOffset
.
I.e. if you use
scrollTopDelta: 64
or[mhScrollTopDelta]="64"
setscrollOffset
to[0, 64]
.
@NgModule({
imports: [RouterModule.forRoot(routes, {
scrollPositionRestoration: 'enabled',
anchorScrolling: 'enabled',
scrollOffset: [0, 64],
})],
exports: [RouterModule]
})
export class AppRoutingModule {
}
In addition to these extra options you optionally need the following global styles for smooth scroll support:
html {
scroll-behavior: smooth;
}
Demo application
Run npm run start
to serve the demo application.
Global configuration
It's possible to provide global defaults for the scroll top delta and scroll behavior:
import { FAKE_FRAGMENT_LINKS_CONFIG, FakeFragmentLinksConfig } from 'ngx-fragment-link-faker';
@NgModule({
providers: [
{
provide: FAKE_FRAGMENT_LINKS_CONFIG,
useFactory: (): FakeFragmentLinksConfig => ({ scrollTopDelta: 84, scrollBehavior: 'smooth' })
}
],
// …
})
export class AppModule {}
Input arguments always take precedence over the global defaults you provide.
Code scaffolding
Run ng generate component component-name --project ngx-fragment-link-faker
to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module --project ngx-fragment-link-faker
.
Note: Don't forget to add
--project ngx-fragment-link-faker
or else it will be added to the default project in yourangular.json
file.
Build
Run npm run build
to build the project. The build artifacts will be stored in the dist/
directory.
Publishing
Run npm run publish
to publish the project.
Further help
To get more help on the Angular CLI use ng help
or go check out the Angular CLI Overview and Command Reference page.
Adheres to / Uses
License
The NgxFragmentLinkFaker library is open-sourced software licensed under the MIT license.