useMode

Käyttötarkoitus

Käytä useMode-hookkia KDS:n komponenttien ulkoasuteeman tilan (tumma/vaalea) tunnistamiseen ja vaihtamiseen.

Ominaisuudet

Oletuksena hook antaa tumman tilan CSS-luokan sovelluksen root-elementille (document.documentElement). Luokan voi tarvittaessa asettaa toiseen elementtiin element-propin avulla. Käytetyn elementin tulee olla sama, jolle on annettu KDS-teeman CSS-luokka.

Mikäli sovellus tarvitsee tummaa tilaa varten myös oman räätälöidyn luokan, esimerkiksi käytössä olevaa laajennusta varten, voidaan sellainen asettaa additionalClassName-propin avulla.

Valitun tilan arvon tallentaminen onnistuu onChange-funktion avulla.

Esimerkit

Tilan asettaminen ja vaihtaminen

Oletustila annetaan defaultMode-propilla.

Tilan hallinta hookin ulkopuolella

Tarvittaessa useMode-hook mahdollistaa myös tilan hallinnan hookin ulkopuolella kontrolloidusti.

Käytä mode-proppia, defaultMode-propin sijasta.

Palvelinpuolen renderöinti (SSR)

Palvelinpuolen renderöinti tai client-koodin hidas latautuminen sattaa aiheuttaa väärän väritilan näkymisen hetkellisesti sivua ladattaessa, joka näkyy välähdyksenä.

Välähdys voidaan välttää suorittamalla alla olevan esimerkin kaltainen alustusskripti mahdollisimman aikaisin head-osiossa ennen Reactin client-koodia.

Esimerkki tilan alustamisesta

<script>
  (() => {
    const STORAGE_MODE_KEY = "APP_MODE";
    const allowedModes = new Set(["light", "dark", "system"]);

    const getStoredValue = (key) => {
      const value = localStorage.getItem(key);
      return allowedModes.has(value) ? value : "system";
    };

    try {
      const mode = getStoredValue(STORAGE_MODE_KEY);
      const isDark = mode === "system" ? matchMedia("(prefers-color-scheme: dark)").matches : mode === "dark";
      const functionalMode = isDark ? "dark" : "light";

      localStorage.setItem(STORAGE_MODE_KEY, functionalMode);
      document.documentElement.classList.toggle("kds-dark", isDark);
    } catch {
      const prefersDark = matchMedia("(prefers-color-scheme: dark)").matches;
      document.documentElement.classList.toggle("kds-dark", prefersDark);
    }
  })();
</script>

Muuta huomioitavaa

• Hookin system-asetusta käytettäessä voi aiheutua hydration(Avautuu uuteen välilehteen)-virheitä, joita voi välttää suorittamalla hookin ainoastaan client-puolella.
• Tila-asetuksen tallentaminen evästeeseen parantaa yhteensopivuutta, sillä eväste on käytettävissä sekä palvelin- että selainpuolella, jolloin tieto tallennetusta tilasta on käytettävissä renderöintitavasta riippumatta.