fullscreen-toggle/README.md

A lightweight utility to toggle fullscreen mode in web applications. Works with all JavaScript frameworks including React, Angular, Vue, and vanilla JS.

# Fullscreen Toggle

A lightweight, cross-browser utility to toggle fullscreen mode in web applications. Works seamlessly with all JavaScript frameworks including React, Angular, Vue, and vanilla JavaScript.

## Installation

```bash
npm install fullscreen-toggle
```

## Usage

### Basic Usage

```javascript
import { toggleFullScreen } from 'fullscreen-toggle';

// Enter fullscreen
toggleFullScreen(true);

// Exit fullscreen
toggleFullScreen(false);
```

### With Promise Support

```javascript
import { toggleFullScreen } from 'fullscreen-toggle';

// Using async/await
try {
  const success = await toggleFullScreen(true);
  if (success) {
    console.log('Entered fullscreen successfully!');
  } else {
    console.log('Failed to enter fullscreen');
  }
} catch (error) {
  console.error('Error:', error);
}

// Using .then()
toggleFullScreen(true)
  .then(success => {
    if (success) {
      console.log('Fullscreen activated!');
    }
  });
```

## Framework Examples

### React

```jsx
import React, { useState } from 'react';
import { toggleFullScreen, isFullScreen, onFullScreenChange } from 'fullscreen-toggle';

function App() {
  const [fullscreen, setFullscreen] = useState(false);

  useEffect(() => {
    // Listen for fullscreen changes
    const cleanup = onFullScreenChange((isFs) => {
      setFullscreen(isFs);
    });
    
    return cleanup; // Cleanup on unmount
  }, []);

  const handleToggle = async () => {
    const success = await toggleFullScreen(!fullscreen);
    if (!success) {
      alert('Fullscreen not supported or failed');
    }
  };

  return (
    <div>
      <button onClick={handleToggle}>
        {fullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen'}
      </button>
    </div>
  );
}
```

### Vue

```vue
<template>
  <div>
    <button @click="handleToggle">
      {{ isFs ? 'Exit Fullscreen' : 'Enter Fullscreen' }}
    </button>
  </div>
</template>

<script>
import { toggleFullScreen, isFullScreen, onFullScreenChange } from 'fullscreen-toggle';

export default {
  data() {
    return {
      isFs: false,
      cleanup: null
    };
  },
  mounted() {
    this.cleanup = onFullScreenChange((isFullScreen) => {
      this.isFs = isFullScreen;
    });
  },
  beforeDestroy() {
    if (this.cleanup) {
      this.cleanup();
    }
  },
  methods: {
    async handleToggle() {
      const success = await toggleFullScreen(!this.isFs);
      if (!success) {
        alert('Fullscreen not supported or failed');
      }
    }
  }
};
</script>
```

### Angular

```typescript
import { Component, OnInit, OnDestroy } from '@angular/core';
import { toggleFullScreen, isFullScreen, onFullScreenChange } from 'fullscreen-toggle';

@Component({
  selector: 'app-fullscreen',
  template: `
    <button (click)="handleToggle()">
      {{ isFullscreen ? 'Exit Fullscreen' : 'Enter Fullscreen' }}
    </button>
  `
})
export class FullscreenComponent implements OnInit, OnDestroy {
  isFullscreen = false;
  private cleanup?: () => void;

  ngOnInit() {
    this.cleanup = onFullScreenChange((isFs) => {
      this.isFullscreen = isFs;
    });
  }

  ngOnDestroy() {
    if (this.cleanup) {
      this.cleanup();
    }
  }

  async handleToggle() {
    const success = await toggleFullScreen(!this.isFullscreen);
    if (!success) {
      alert('Fullscreen not supported or failed');
    }
  }
}
```

### Vanilla JavaScript

```javascript
import { toggleFullScreen, isFullScreenSupported } from 'fullscreen-toggle';

const button = document.getElementById('fullscreen-btn');

if (isFullScreenSupported()) {
  button.addEventListener('click', async () => {
    const isCurrentlyFullscreen = isFullScreen();
    const success = await toggleFullScreen(!isCurrentlyFullscreen);
    
    if (success) {
      button.textContent = isCurrentlyFullscreen ? 'Enter Fullscreen' : 'Exit Fullscreen';
    } else {
      console.error('Failed to toggle fullscreen');
    }
  });
} else {
  button.disabled = true;
  button.textContent = 'Fullscreen not supported';
}
```

## API Reference

### `toggleFullScreen(goFullScreen: boolean): Promise<boolean>`

Toggles fullscreen mode.

- **goFullScreen**: `true` to enter fullscreen, `false` to exit
- **Returns**: Promise that resolves to `true` if successful, `false` otherwise

### `isFullScreen(): boolean`

Checks if the browser is currently in fullscreen mode.

- **Returns**: `true` if in fullscreen, `false` otherwise

### `isFullScreenSupported(): boolean`

Checks if the Fullscreen API is supported by the browser.

- **Returns**: `true` if supported, `false` otherwise

### `onFullScreenChange(callback: (isFullScreen: boolean) => void): () => void`

Adds an event listener for fullscreen state changes.

- **callback**: Function called when fullscreen state changes
- **Returns**: Cleanup function to remove the event listener

## Browser Support

- ✅ Chrome 15+
- ✅ Firefox 64+
- ✅ Safari 16.4+
- ✅ Edge 12+
- ✅ Opera 15+
- ✅ Internet Explorer 11

## Features

- 🚀 **Lightweight**: Less than 2KB gzipped
- 🌐 **Cross-browser**: Handles vendor prefixes automatically
- 📱 **Framework agnostic**: Works with React, Vue, Angular, and vanilla JS
- 💪 **TypeScript**: Full TypeScript support with type definitions
- 🔄 **Promise-based**: Modern async/await support
- 📡 **Event handling**: Listen for fullscreen changes
- 🛡️ **Error handling**: Graceful fallbacks and error handling

## License

MIT

## Contributing

Pull requests are welcome! Please read our contributing guidelines first.

## Issues

If you find any issues or have feature requests, please open an issue on our [GitHub repository](https://github.com/yourusername/fullscreen-toggle/issues).