Esikatselu
<ToggleSwitch labelText="Ilmoitukset" />
Käyttötarkoitus
ToggleSwitch on komponentti valintakytkimen toteuttamiseen. Valintakytkintä voidaan käyttää tilanteissa, joissa käyttäjän täytyy tehdä valinta kahden toisensa pois sulkevan päälle/pois-tilan väliltä. Toinen komponentin tila on aina valittuna.
Valintakytkimellä on tarkoitus hallita heti tapahtuvaa muutosta, se ei sovi käytettäväksi lomakkeissa.
Komponentti sopii esimerkiksi asetuksiin ja tilanteisiin, joissa valinta on helposti ymmärrettävissä ja se on helppo tehdä.
Saavutettavuus
Komponentti toteuttaa yksittäisen painikkeen. Painike tulostetaan button-elementtinä aria-pressed-attribuutilla, jolloin ruudunlukija kuvailee elementin ja lukee sen tilan asianmukaisesti.
Esimerkit
Valinnan tilan tekstivastine
Valinnan tila voidaan näyttää tarvittaessa myös tekstinä komponentin vierellä.
<ToggleSwitch labelText="Ilmoitukset" stateLabel={{ on: "Päällä", off: "Pois" }} />
Yksirivinen valintakytkin
<ToggleSwitch defaultChecked inline labelText="Ilmoitukset" stateLabel={{ on: "Päällä", off: "Pois" }} />
Värit
<>
<ToggleSwitch defaultChecked labelText="Ilmoitukset" variant="primary" />
<ToggleSwitch defaultChecked labelText="Ilmoitukset" variant="neutral" />
</>
Kokovaihtoehdot
<>
<ToggleSwitch className="kds-mb-4" defaultChecked inline labelText="Ilmoitukset" size="sm" variant="primary" />
<ToggleSwitch className="kds-mb-4" defaultChecked inline labelText="Ilmoitukset" size="md" variant="primary" />
<ToggleSwitch defaultChecked inline labelText="Ilmoitukset" size="lg" variant="primary" />
</>
Estetty tila
<>
<ToggleSwitch className="kds-mb-2" disabled inline labelText="Ilmoitukset" variant="primary" />
<ToggleSwitch className="kds-mb-2" defaultChecked disabled inline labelText="Ilmoitukset" variant="primary" />
</>
Kaksipalstainen asettelu
Kaksipalstaisessa asettelussa tulostetaan leftCol-propilla kentän nimilappu ja aputeksti Column-komponentin sisään.
<ToggleSwitch
helpText="Vastaanota sähköpostiin ilmoituksia palvelun muutoksista."
labelText="Ilmoitukset"
leftCol={(children) => <Column md={8}>{children}</Column>}
/>
Räätälöity asettelu
Asettelun voi tarvittaessa rakentaa räätälöidysti liittämällä valintakytkimeen oman nimilapun ja ohjetekstin. Huomaa, että komponentin saavutettava toteutus jää tällöin osin sovelluksen vastuulle.
<Box className="kds-flex kds-items-center kds-justify-between">
<div className="kds-mr-4">
<InputLabel id="toggle-label-1" htmlFor="toggle-1">
Ilmoitukset
</InputLabel>
<InputText id="toggle-help-text-1">Vastaanota sähköpostiin ilmoituksia palvelun muutoksista.</InputText>
</div>
<ToggleSwitch
aria-labelledby="toggle-label-1"
aria-describedby="toggle-help-text-1"
id="toggle-1"
defaultChecked={true}
/>
</Box>
Kontrolloitu käyttö
Kontrolloidusti käytettäessä painikkeen tilaa hallitaan useState-hookin avulla.
function ToggleSwitchExample() {
const [isActive, setIsActive] = useState(false);
return (
<>
<ToggleSwitch
checked={isActive}
id="setting-toggle"
inline
labelText="Ilmoitukset"
onClick={(_, checked) => setIsActive(checked)}
/>
<pre className="kds-mt-6">isActive: {String(isActive)}</pre>
</>
);
}