# ๐บ Fullscreen Service for Angular
An Angular service and **directives** that provide **fullscreen control**, **reactive state**, and **template-friendly utilities**.
Originally published as a **service-only package**, this library has been **extended in a fully backward-compatible way** to include Angular directives and reactive APIs โ existing applications continue to work unchanged.
---
## โจ Features
### Core
- โ Optional double-tap toggle to reduce accidental activation
- โ Single-tap toggle by default
- ๐ **watchFullscreen events**
- โ Backward-compatible service API
- โ Cross-browser Fullscreen API support
- โ No external dependencies
- โ Small footprint
### Enhanced (FullscreenModule)
- ๐ **Reactive fullscreen state** (`fullscreen$`)
- ๐ **Structural and attribute directives**
fsToggle, fsExit, fsDoubleTap, fsActiveClass, *ifFullscreen,
- ๐ **Double-tap fullscreen toggle** (customizable)
- ๐ **CSS class binding when fullscreen is active**
---
## ๐ฆ Installation
```bash
npm install @cradokski/fullscreen
```
---
## ๐ Basic Usage (Unchanged)
### Service Injection
```ts
import { FullScreenService } from '@cradokski/fullscreen';
@Component({...})
export class AppComponent {
constructor(public fsService: FullScreenService) {}
}
```
### Template Example
```html
```
โ๏ธ **No changes required** for existing consumers.
---
## ๐ฆ Angular Module Usage
```ts
import { FullscreenModule } from '@cradokski/fullscreen';
@NgModule({
imports: [FullscreenModule]
})
export class AppModule {}
```
---
## ๐ง Service API
### **browserFsToggle(options?)**
```ts
browserFsToggle(options?: {
requireDoubleTap?: boolean;
delayMs?: number;
}): boolean
```
| Option | Type | Default | Description |
|--------------------|-----------|---------|-------------|
| `requireDoubleTap` | boolean | false | Require two taps within `delayMs` to toggle |
| `delayMs` | number | 300 | Maximum time between taps (ms) |
**Returns:** `true` if fullscreen is active after the call.
---
### **browserFsToggleAsync(options?)**
```ts
browserFsToggleAsync(options?): Promise
```
Async version of `browserFsToggle`.
---
### **watchFullscreen(callback)**
```ts
watchFullscreen(
callback: (isFullscreen: boolean, element: Element | null) => void
): () => void
```
Registers a fullscreen watcher. The Callback fires immediately with the current state and
Fires again on every fullscreen change
Returns an unwatch() cleanup function
example :
```ts
private unwatch: (() => void) | null = null;
ngOnInit(): void {
this.unwatch = fsService.watchFullscreen((isFs, element) => {
console.log('Fullscreen active:', isFs);
console.log('Fullscreen element:', element?.tagName);
});
}
// Cleanup when no longer needed
ngOnDestroy(): void {
if (this.unwatch) this.unwatch();
}
```
---
### **toggleFullscreen(element?)**
```ts
toggleFullscreen(element?: HTMLElement): Promise<'entered' | 'exited'>
```
Toggles fullscreen on a specific element (defaults to ``).
```html
```
---
### **ensureFullscreen(element?)**
```ts
ensureFullscreen(element?): Promise<'entered'>
```
Idempotent โ only enters fullscreen if not already active.
```html
```
---
### **ensureExitedFullscreen()**
```ts
ensureExitedFullscreen(): Promise<'exited'>
```
Idempotent โ only exits fullscreen if active.
```html
```
---
### **isFullscreenActive()**
```ts
isFullscreenActive(): boolean
```
Synchronous fullscreen state check.
```html
Fullscreen Active using fsService.isFullscreenActive()
Normal using fsService.isFullscreenActive()
```
---
## ๐ Reactive API
### **fullscreen$**
Observable of reactive fullscreen state
```ts
this.fsService.fullscreen$.subscribe(state => {
console.log("Fullscreen state changed:", state.active, state.element);
});
```
---
## ๐งฉ Directives
### ๐ `fsToggle`
Toggles fullscreen mode on the host element.
```html
```
### ๐ช `fsExit`
Exits fullscreen mode when clicked.
```html
```
### ๐ `fsDoubleTap`
Requires double-click / double-tap to toggle fullscreen.
```html
```
### ๐จ `fsActiveClass`
Automatically adds the CSS class fs-active to the host element while fullscreen is active.
```html
I get class `.fs-active` when fullscreen mode is active
/* CSS example */
.fs-active {
background: #0078ff;
color: white;
}
```
### ๐งฑ `*ifFullscreen - Structural Directive`
Conditionally renders content only while fullscreen is active.
```html
Visible only in fullscreen mode
```
---
## ๐งช Angular Compatibility
- Built with Angular CLI **v18.2.x**
- Compatible with **Angular v16+**
- Supports standalone components and NgModules
---
## ๐ License
MIT