leaflet.fullscreen/README.md

Simple plugin for Leaflet that adds fullscreen button to your maps.

# Leaflet Control FullScreen

## What ?

**Leaflet Control FullScreen** is a simple plugin for [Leaflet](https://leafletjs.com/) that adds a fullscreen button to your maps using the Fullscreen API.

All major browsers support the Fullscreen API. For details about which browsers support this API, see the [CanIuse](https://caniuse.com/fullscreen) website.

## How ?

Include `Control.FullScreen.umd.js` and `Control.FullScreen.css` in your page:

```html
<link rel="stylesheet" href="https://unpkg.com/leaflet.fullscreen/dist/Control.FullScreen.css" />
<script src="https://unpkg.com/leaflet.fullscreen/dist/Control.FullScreen.umd.js"></script>
```

If you want to host the files yourself, you can download them from [npm](https://www.npmjs.com/package/leaflet.fullscreen) or clone this repository and run `npm run build`.

Add the fullscreen control to the map:

```js
const map = L.map('map');

map.addControl(new L.Control.FullScreen());
```

If your map has a zoomControl, the fullscreen button will be added at the bottom of it.

If your map doesn't have a zoomControl, the fullscreen button will be added to the topleft corner of the map (default position).

If you want to use the plugin on a map embedded in an iframe, don't forget to set `allowfullscreen` attribute on your iframe.

**Option, events and methods**:

```js
// create a fullscreen button and add it to the map
new L.Control.FullScreen({
	position: 'topleft', // change the position of the button can be topleft, topright, bottomright or bottomleft, default topleft
	title: 'Show me the fullscreen !', // change the title of the button, default Full Screen
	titleCancel: 'Exit fullscreen mode', // change the title of the button when fullscreen is on, default Exit Full Screen
	content: null, // change the content of the button, can be HTML, default null
	forceSeparateButton: true, // force separate button to detach from zoom buttons, default false
	forcePseudoFullscreen: true, // force use of pseudo full screen even if full screen API is available, default false
	fullscreenElement: false // Dom element to render in full screen, false by default, fallback to map._container
}).addTo(map);

// events are fired when entering or exiting fullscreen.
map.on('enterFullscreen', function () {
	console.log('entered fullscreen');
});

map.on('exitFullscreen', function () {
	console.log('exited fullscreen');
});

// you can also toggle fullscreen from map object
map.toggleFullscreen();
```

## Customization

This plugin uses CSS variables for icons, eliminating the need for external image files. You can easily customize the icons by overriding the CSS variables:

```css
:root {
	--fullscreen-icon-enter: url('data:image/svg+xml;...');
	--fullscreen-icon-exit: url('data:image/svg+xml;...');
}
```

## Where ?

- Source code: <https://github.com/brunob/leaflet.fullscreen>
- Downloads: <https://github.com/brunob/leaflet.fullscreen/releases>
- Demo: <https://brunob.github.io/leaflet.fullscreen/>

## Use as ES module

To use this plugin with a bundler (Webpack, Vite, etc.):

1. Install leaflet.fullscreen with your package manager:

   ```bash
   npm install leaflet.fullscreen
   ```

2. Import the module in your code:

   ```js
   // Named export (recommended)
   import { FullScreen } from 'leaflet.fullscreen';

   // Add control to your map
   map.addControl(
   	new FullScreen({
   		position: 'topleft'
   	})
   );
   ```

   Alternatively, you can use the default export:

   ```js
   // Default export (also works)
   import FullScreen from 'leaflet.fullscreen';

   map.addControl(new FullScreen());
   ```

3. Import the CSS (if your bundler supports it):

   ```js
   import 'leaflet.fullscreen/dist/Control.FullScreen.css';
   ```

   Or add it manually to your HTML:

   ```html
   <link rel="stylesheet" href="node_modules/leaflet.fullscreen/dist/Control.FullScreen.css" />
   ```

## Contributing

If you find any problems, bugs or have questions, please [open a GitHub issue](https://github.com/brunob/leaflet.fullscreen/issues) in this repository.

Pull requests are of course also very welcome 🙂

The [CHANGELOG.md](CHANGELOG.md) is generated with `commit-and-tag-version` (using the command `npm run release`).

To make this possible the commit messages / pull request titles must follow the [conventional commits specification](https://www.conventionalcommits.org/en/v1.0.0/).

```
<type>: <subject>

[optional body]

[optional footer(s)]
```

The following is the list of supported types:

- build: changes that affect build components like build tool, ci pipeline, dependencies, project version, etc...
- chore: changes that aren't user-facing (e.g. merging branches).
- ci: changes to the CI configuration files and scripts (basically directory .github/workflows).
- docs: changes that affect the documentation only.
- feat: changes that introduce a new feature.
- fix: changes that patch a bug.
- perf: changes which improve performance.
- refactor: changes which neither fix a bug nor add a feature.
- revert: changes that revert a previous commit.
- style: changes that don't affect code logic, such as white-spaces, formatting, missing semi-colons.
- test: changes that add missing tests or correct existing tests.

For breaking changes a footer with the following content must be used.
BREAKING CHANGE: <description of what is broken by this commit>

### Developer commands

- `npm run build` - Build the distribution files from source.
- `npm run lint` - Run linting and formatter checks.
- `npm run lint:fix` - Fix linting and formatter issues.

## Credits

- This plugin is inspired by [leaflet.zoomfs](https://github.com/elidupuis/leaflet.zoomfs) from elidupuis.
- Icons from [Font Awesome v5.15.4](https://github.com/FortAwesome/Font-Awesome/releases/tag/5.15.4): [Creative Commons Attribution 4.0](https://fontawesome.com/license/free).

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE.md) file for details.