<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

*   [DarkMode][1]
    *   [inDarkMode][2]
        *   [Examples][3]
    *   [hasGDPRConsent][4]
        *   [Examples][5]
    *   [cookieExpiry][6]
    *   [documentRoot][7]
    *   [readValue][8]
        *   [Parameters][9]
    *   [eraseValue][10]
        *   [Parameters][11]
    *   [getSavedColorScheme][12]
    *   [getPreferedColorScheme][13]
    *   [setDarkMode][14]
        *   [Parameters][15]
        *   [Examples][16]
    *   [toggleDarkMode][17]
        *   [Parameters][18]
        *   [Examples][19]
    *   [resetDarkMode][20]
        *   [Examples][21]
    *   [DATA_KEY][22]
    *   [VALUE_LIGHT][23]
    *   [VALUE_DARK][24]
    *   [CLASS_NAME_LIGHT][25]
    *   [CLASS_NAME_DARK][26]
    *   [getColorScheme][27]
    *   [updatePreferedColorSchemeEvent][28]
    *   [onDOMContentLoaded][29]
*   [darkmode][30]

## DarkMode

*bootstrap-dark-5* `darkmode.js` -- the JavaScript module.

***class*** **DarkMode**

Use this JS file, and its `darkmode` object, in your HTML to automatically capture `prefers-color-scheme` media query
events and also initialize tags with the `data-bs-color-scheme` attribute, or the document root (`<HTML>` tag) with the
user preferred color scheme.

The `darkmode` object can also be used to drive a dark mode toggle event, with optional persistance
storage in either a cookie (if GDPR consent is given) or the browsers `localStorage` object.

The module can be loaded into a html page using a standard script command.

```html
<script src="darkmode.js"></script>
```

This will create a variable `darkmode` that is an instance of the DarkMode class.

Once the DOM is loaded the script will then look for any html tag with a `data-bs-color-scheme` attribute, and, if found
will use these tags to populate the current mode.  If this data attribute is not found then the script will use the document
root (`<HTML>` tag) with the class `dark` or `light`.

For example, the `bootstrap-blackbox.css` variant requires the `<HTML>` to be initialized:

```html
<!doctype html>
<html lang="en" data-bs-color-scheme>
  <head>
    <!-- ... -->
```

You can also pre-initialize the mode by populating the data attribute:

```html
<html lang="en" data-bs-color-scheme="dark">
```

### inDarkMode

***property***

Used to get the current state, `true` when in dark mode, `false` when in light mode or when mode not set

Can also be used to set the current mode *(with no persistance saving)*

Type: [boolean][31]

#### Examples

Get if page is in "Dark" mode

```javascript
var myVal = darkmode.inDarkMode;
```

Set the page to the "Dark" mode

```javascript
darkmode.inDarkMode = true;
```

### hasGDPRConsent

Variable to store GDPR Consent.  This setting drives the persistance mechanism.

Used in [#saveValue][32] to determine if a cookie or the `localStorage` object should be used.

*   Set to `true` when GDPR Consent has been given to enable storage to cookie *(useful in Server-Side knowledge of user preference)*
*   The setter takes care of swapping the cookie and localStorage if appropriate
*   Default is `false`, thus storage will use the browsers localStorage object *(Note: No expiry is set)*

#### Examples

Set once GDPR consent is given by the user

```javascript
darkmode.hasGDPRConsent = true;
```

### cookieExpiry

Expiry time in days when saving and GDPR consent is give

### documentRoot

Saves the instance of the documentRoot (i.e. `<html>` tag) when the object is created.

Type: [HTMLHtmlElement][33]

Returns **[HTMLHtmlElement][33]** 

### readValue

Retrieves the color-scheme last saved

**NOTE:** is dependant on [#hasGDPRConsent][34]

#### Parameters

*   `name` **[string][35]** \-- Name of the cookie or localStorage->name

Returns **[string][35]** \-- The saved value, either `light` or `dark`, or an empty string if not saved prior

### eraseValue

Deletes the saved color-scheme

**NOTE:** is dependant on [#hasGDPRConsent][34]

#### Parameters

*   `name` **[string][35]** 

Returns **void** \-- Nothing, erasure is assumed

### getSavedColorScheme

Queries the `<HTML>` tag for the current color-scheme

*(This value is set prior via the [#setDarkMode][36]) function.)*

Returns **[string][35]** \-- The current value, either `light` or `dark`, or an empty string if not saved prior

### getPreferedColorScheme

Queries the `prefers-color-scheme` media query for the current color-scheme

*(This value is set prior via the [#setDarkMode][36]) function.)*

Returns **[string][35]** \-- The current value, either `light` or `dark`, or an empty string if the media query is not supported

### setDarkMode

Sets the color-scheme in the `<HTML>` tag as a class called either `light` or `dark`

**Note:** This function will modify your document root element, i.e. the `<HTML>` tag

Default behavior when setting dark mode `true`

```html
<html lang="en" class="other-classes dark">
<!-- Note: the "light" class is removed -->
```

Default behavior when setting dark mode `false`

```html
<html lang="en" class="other-classes light">
<!-- Note: the "dark" class is removed -->
```

Behavior when setting dark mode `true`, and `dataSelector = "data-bs-color-scheme"`

```html
<html lang="en" data-bs-color-scheme="dark">
```

Behavior when setting dark mode `false`, and `dataSelector = "data-bs-color-scheme"`

```html
<html lang="en" data-bs-color-scheme="light">
```

#### Parameters

*   `darkMode` **[boolean][31]** \-- `true` for "dark", `false` for 'light'
*   `doSave` **[boolean][31]** \-- If `true`, then will also call [#saveValue][32] to save that state (optional, default `true`)

#### Examples

Set the color scheme to ***dark***, saving the state to the persistance mechanism

```javascript
document.querySelector("#darkmode-on-button").onclick = function(e){
  darkmode.setDarkMode(true);  // save=true is default
}
```

Set the color scheme to ***light***, but not saving the state

```javascript
document.querySelector("#darkmode-off-button-no-save").onclick = function(e){
  darkmode.setDarkMode(false, false);
}
```

Returns **void** \-- Nothing, assumes saved

### toggleDarkMode

Toggles the color scheme in the `<HTML>` tag as a class called either `light` or `dark`
based on the inverse of it's prior state.

When [#dataSelector][37] is set, this is set in the given data selector as the data value.

*(See [#setDarkMode][36])*

#### Parameters

*   `doSave`   (optional, default `true`)

#### Examples

Bind an UI Element `click` event to toggle dark mode

```javascript
document.querySelector("#darkmode-button").onclick = function(e){
  darkmode.toggleDarkMode();
}
```

Returns **void** Nothing, assumes success

### resetDarkMode

Clears the persistance state of the module and resets the document to the default mode.

Calls [#eraseValue][38] to erase any saved value, and then
calls [#getPreferedColorScheme][39] to retrieve the `prefers-color-scheme` media query,
passing its value to [#setDarkMode][36] to reset the users preference.

#### Examples

Bind a reset UI Element `click` event to reset the dark mode

```javascript
document.querySelector("#darkmode-forget").onclick = function(e){
  darkmode.resetDarkMode();
}
```

Returns **void** Nothing, no error handling is performed.

### DATA_KEY

***const*** -- Name of the cookie or localStorage->name when saving

### VALUE_LIGHT

***const*** -- String used to identify light mode *(do not change)*, @see [https://www.w3.org/TR/mediaqueries-5/#prefers-color-scheme][40]

### VALUE_DARK

***const*** -- String used to identify dark mode *(do not change)*, @see [https://www.w3.org/TR/mediaqueries-5/#prefers-color-scheme][40]

### CLASS_NAME_LIGHT

***const*** -- String used to identify light mode as a class in the `<HTML>` tag

### CLASS_NAME_DARK

***const*** -- String used to identify dark mode as a class in the `<HTML>` tag

### getColorScheme

Gets the current color-scheme from the document `<HTML>` tag

Returns **[string][35]** \-- The current value, either `light` or `dark`, or an empty string if not present

### updatePreferedColorSchemeEvent

***static*** -- function called by the media query on change event.

First retrieves any persistent/saved value, and if present ignores the event, but
if not set then triggers the [#setDarkMode][36] function to change the current mode.

Returns **void** \-- Nothing, assumes success

### onDOMContentLoaded

***static*** -- function called when the DOM finishes loading.

Does all the DarkMode initialization, including:

*   Loading any prior stored preference (GDPR consent is ***not*** assumed)
*   else, honoring any `<HTML>` tag `class="dark|light"` that Server-Side may set
*   else, honoring the browser / OS `prefers-color-scheme` preference

and setting the derived mode by calling [#setDarkMode][36]

Followed by setting up the media query on change event

***Warning:*** This function is automatically called when loading this module.

Returns **void** 

## darkmode

***const*** -- This is the global instance (object) of the DarkMode class.

[1]: #darkmode

[2]: #indarkmode

[3]: #examples

[4]: #hasgdprconsent

[5]: #examples-1

[6]: #cookieexpiry

[7]: #documentroot

[8]: #readvalue

[9]: #parameters

[10]: #erasevalue

[11]: #parameters-1

[12]: #getsavedcolorscheme

[13]: #getpreferedcolorscheme

[14]: #setdarkmode

[15]: #parameters-2

[16]: #examples-2

[17]: #toggledarkmode

[18]: #parameters-3

[19]: #examples-3

[20]: #resetdarkmode

[21]: #examples-4

[22]: #data_key

[23]: #value_light

[24]: #value_dark

[25]: #class_name_light

[26]: #class_name_dark

[27]: #getcolorscheme

[28]: #updatepreferedcolorschemeevent

[29]: #ondomcontentloaded

[30]: #darkmode-1

[31]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

[32]: #saveValue

[33]: https://developer.mozilla.org/docs/Web/API/HTMLHtmlElement

[34]: #hasGDPRConsent

[35]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[36]: #setDarkMode

[37]: #dataSelector

[38]: #eraseValue

[39]: #getPreferedColorScheme

[40]: https://www.w3.org/TR/mediaqueries-5/#prefers-color-scheme