-
Notifications
You must be signed in to change notification settings - Fork 90
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #5698 from nextcloud-libraries/feat/is-dark-theme
feat: add isDarkTheme functions and composables
- Loading branch information
Showing
12 changed files
with
196 additions
and
13 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,72 @@ | ||
<!-- | ||
- SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
- SPDX-License-Identifier: AGPL-3.0-or-later | ||
--> | ||
|
||
```ts static | ||
import { | ||
useIsDarkTheme, | ||
useIsDarkThemeElement, | ||
} from '@nextcloud/vue/dist/Composables/useIsDarkTheme.js' | ||
``` | ||
|
||
Same as `isDarkTheme` functions, but with reactivity. | ||
|
||
## Definition | ||
|
||
```ts static | ||
/** | ||
* Check whether the dark theme is enabled on a specific element. | ||
* If you need to check an entire page, use `useIsDarkTheme` instead for better performance. | ||
* Reacts on element attributes change and system theme change. | ||
* @param el - The element to check for the dark theme enabled on, default is document.body | ||
* @return - computed boolean whether the dark theme is enabled | ||
*/ | ||
declare function useIsDarkThemeElement(el: MaybeRef<HTMLElement> = document.body): DeepReadonly<Ref<boolean>> | ||
|
||
/** | ||
* Shared composable to check whether the dark theme is enabled on the page. | ||
* Reacts on body data-theme-* attributes change and system theme change. | ||
* @return - computed boolean whether the dark theme is enabled | ||
*/ | ||
declare function useIsDarkTheme(): DeepReadonly<Ref<boolean>> | ||
``` | ||
|
||
## Example | ||
|
||
```vue | ||
<template> | ||
<div> | ||
<div :style="{ backgroundColor: isDarkTheme ? 'black' : 'white' }"> | ||
Is dark theme enabled? {{ isDarkTheme }} | ||
</div> | ||
<NcButton @click="switchTheme">Switch theme</NcButton> | ||
</div> | ||
</template> | ||
<script> | ||
export default { | ||
setup() { | ||
const isDarkTheme = useIsDarkTheme() | ||
// For documentation only. Do not use in production. | ||
function switchTheme() { | ||
if (isDarkTheme.value) { | ||
document.body.setAttribute('data-theme-light', '') | ||
document.body.removeAttribute('data-theme-dark') | ||
document.body.setAttribute('data-themes', 'light') | ||
} else { | ||
document.body.setAttribute('data-theme-dark', '') | ||
document.body.removeAttribute('data-theme-light') | ||
document.body.setAttribute('data-themes', 'dark') | ||
} | ||
} | ||
return { | ||
isDarkTheme, | ||
switchTheme, | ||
} | ||
}, | ||
} | ||
</script> | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
<!-- | ||
- SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
- SPDX-License-Identifier: AGPL-3.0-or-later | ||
--> | ||
|
||
```ts static | ||
import { | ||
isDarkTheme, | ||
checkIfDarkTheme, | ||
} from '@nextcloud/vue/dist/Functions/isDarkTheme.js' | ||
``` | ||
|
||
Check whether the dark theme is enabled in Nextcloud. | ||
|
||
You should not use `window.matchMedia.('(prefers-color-scheme: dark)')`. It checks for the user's system theme, but Nextcloud Dark theme could be enabled even on the light system theme. | ||
|
||
You should not use `[data-themes*=dark]` or `[data-theme-dark]` attributes on the body. It checks for explicitly set dark theme, but a user may use the system or custom theme. | ||
|
||
## Definitions | ||
|
||
```ts static | ||
/** | ||
* Check whether the dark theme is used on a specific element | ||
* @param el - Element to check for dark theme, which is used for `data-theme-*` checking (default is `document.body`) | ||
* @return - Whether the dark theme is enabled via Nextcloud theme | ||
*/ | ||
declare function checkIfDarkTheme(el: HTMLElement = document.body): boolean; | ||
|
||
/** | ||
* Whether the dark theme is enabled in Nextcloud. | ||
* The variable is defined on page load and not reactive. | ||
* Use `checkIfDarkTheme` if you need to check it at a specific moment. | ||
* Use `useDarkTheme` if you need a reactive variable in a Vue component. | ||
*/ | ||
declare var isDarkTheme | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
/** | ||
* SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
* SPDX-License-Identifier: AGPL-3.0-or-later | ||
*/ | ||
|
||
import type { DeepReadonly, Ref } from 'vue' | ||
import { ref, readonly, watch } from 'vue' | ||
import { createSharedComposable, usePreferredDark, useMutationObserver } from '@vueuse/core' | ||
import { checkIfDarkTheme } from '../../functions/isDarkTheme/index.ts' | ||
|
||
/** | ||
* Check whether the dark theme is enabled on a specific element. | ||
* If you need to check an entire page, use `useIsDarkTheme` instead for better performance. | ||
* Reacts on element attributes change and system theme change. | ||
* @param el - The element to check for the dark theme enabled on (default is `document.body`) | ||
* @return {DeepReadonly<Ref<boolean>>} - computed boolean whether the dark theme is enabled | ||
*/ | ||
export function useIsDarkThemeElement(el: HTMLElement = document.body): DeepReadonly<Ref<boolean>> { | ||
const isDarkTheme = ref(checkIfDarkTheme(el)) | ||
const isDarkSystemTheme = usePreferredDark() | ||
|
||
/** Update the isDarkTheme */ | ||
function updateIsDarkTheme() { | ||
isDarkTheme.value = checkIfDarkTheme(el) | ||
} | ||
|
||
// Watch for element change to handle data-theme* attributes change | ||
useMutationObserver(el, updateIsDarkTheme, { attributes: true }) | ||
// Watch for system theme change for the default theme | ||
watch(isDarkSystemTheme, updateIsDarkTheme, { immediate: true }) | ||
|
||
return readonly(isDarkTheme) | ||
} | ||
|
||
/** | ||
* Shared composable to check whether the dark theme is enabled on the page. | ||
* Reacts on body data-theme-* attributes change and system theme change. | ||
* @return {DeepReadonly<Ref<boolean>>} - computed boolean whether the dark theme is enabled | ||
*/ | ||
export const useIsDarkTheme = createSharedComposable(() => useIsDarkThemeElement()) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,32 @@ | ||
/** | ||
* SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors | ||
* SPDX-License-Identifier: AGPL-3.0-or-later | ||
*/ | ||
|
||
/** | ||
* Check whether the dark theme is used on a specific element | ||
* @param el - Element to check for dark theme, which is used for `data-theme-*` checking (default is `document.body`) | ||
* @return {boolean} - Whether the dark theme is enabled via Nextcloud theme | ||
*/ | ||
export function checkIfDarkTheme(el: HTMLElement = document.body): boolean { | ||
// Nextcloud uses --background-invert-if-dark for dark theme filters in CSS | ||
// Values: | ||
// - 'invert(100%)' for dark theme | ||
// - 'no' for light theme | ||
// This is the most reliable way to check for dark theme, including custom themes | ||
const backgroundInvertIfDark = window.getComputedStyle(el).getPropertyValue('--background-invert-if-dark') | ||
if (backgroundInvertIfDark !== undefined) { | ||
return backgroundInvertIfDark === 'invert(100%)' | ||
} | ||
|
||
// There is no theme? Fallback to the light theme | ||
return false | ||
} | ||
|
||
/** | ||
* Whether the dark theme is enabled in Nextcloud. | ||
* The variable is defined on page load and not reactive. | ||
* Use `checkIfDarkTheme` if you need to check it at a specific moment. | ||
* Use `useDarkTheme` if you need a reactive variable in a Vue component. | ||
*/ | ||
export const isDarkTheme = checkIfDarkTheme() |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters