CheckboxGroup
CheckboxGroup samler flere relaterte checkboxer i én gruppe der brukeren kan velge ett eller flere alternativer samtidig. Hvert valg er uavhengig av de andre.
Egnet til
- Når brukeren skal kunne velge flere alternativer samtidig
- Filtrering der flere valg kan kombineres
- Samtykker eller preferanser der hvert valg er uavhengig
- Kortere lister med tydelige forskjeller mellom alternativene
Uegnet til
- Når brukeren kun skal velge ett alternativ (bruk RadioGroup)
- Lange lister med mange alternativer (vurder Select)
- Situasjoner der valgene er gjensidig utelukkende
- En enkeltstående checkbox uten gruppe-kontekst (bruk Checkbox)
Bruk
For enkle lister er options-propen den raskeste veien, på samme måte som Select. Hver option har value og label.
I praksis vil du som regel holde valgte verdier i state og koble dem via value/onChange. Merk at value er et array: flere kan være valgt samtidig. onChange er event-basert (verdien ligger i event.target.value, av/på i event.target.checked), slik at et {...register('felt')} fra React Hook Form kan spres rett på komponenten. Se Form-validering.
Bruker du ikke React Hook Form, gir useCheckboxGroup-hooken deg kontrollert array-state uten at du selv må bygge neste array. Den returnerer { value, onChange } klar til å spres på komponenten, og value er string[] du kan bruke til å vise/skjule avhengige seksjoner:
import { CheckboxGroup, useCheckboxGroup } from '@sb1/indeks-react';
const kontakt = useCheckboxGroup(['epost']);
<CheckboxGroup
legend="Hvordan vil du bli kontaktet?"
name="kontakt"
{...kontakt}
options={[
{ value: 'epost', label: 'E-post' },
{ value: 'sms', label: 'SMS' },
{ value: 'telefon', label: 'Telefon' },
]}
/>
Trenger du bare selve array-oppdateringen i din egen state, bruk den rene funksjonen toggleValue(prev, event). Det er den samme oppskriften hooken bygger på.
Trenger du deaktiverte alternativer, egne id-er eller en ref, bruker du CheckboxButton-barn i stedet:
Komponenten håndterer name-propagering og ARIA-kobling automatisk. Hver CheckboxButton må ha en unik value innenfor gruppen. Hvis både options og children er satt, vinner options.
Eksempler
Med beskrivelse
Bruk description for å gi ekstra kontekst til hele gruppen.
Med feilmelding
Når validering feiler, vis en feilmelding som forklarer hva som er galt og hva brukeren skal gjøre. <ix-checkbox-group> setter aria-invalid="true" på gruppen automatisk når error-elementet har innhold.
Skjult legend
I tabeller eller andre kontekster der gruppe-konteksten allerede er gitt, kan legend skjules visuelt. Den skal fortsatt være meningsfull. Skjermlesere leser den.
Skrivebeskyttet og deaktivert
readOnly viser valgene men hindrer endring. disabled gjør hele gruppen inaktiv. Vurder om disabled er riktig. Alternativet kan ofte heller skjules eller forklares.
Retningslinjer
Skriv en legend som stiller spørsmålet
Legenden er spørsmålet alternativene svarer på: "Hvordan vil du varsles?", ikke "Varsling". Uten den står brukeren med en liste avkryssinger og må gjette hva de har til felles.
Gjelder det bare ett av/på-valg, som «Jeg godtar vilkårene», bruk en enkeltstående Checkbox.
Vis alternativene under hverandre
Vertikal liste er hovedregelen. Én kolonne kan skannes nedover, tåler zoom og brekker ikke på smal skjerm, og alternativer med ulik tekstlengde ligger fortsatt på linje til venstre.
Velg rekkefølgen bevisst
Sorter logisk eller alfabetisk, så leter ikke brukeren. I lange lister kan de mest brukte valgene ligge øverst, men vær klar over at det du legger først, blir valgt oftere.
Del opp lange lister
En liste med tjue avkryssinger er tung å holde oversikt over. Del den i flere grupper med egne legender, eller la brukeren filtrere seg fram til det som er relevant.
Designvalg
CheckboxGroup bruker role="group" framfor <fieldset>, value er et array, og
aria-invalid settes bare på gruppen og ikke på hver checkbox.
Designvalg for CheckboxGroup går gjennom avveiningene, og hva som skiller CheckboxGroup fra RadioGroup.
Universell utforming
Hva du selv må sørge for
- Beskrivende legend: komponenten kobler legend til gruppen, men du må skrive god tekst
- Beskrivende labels: hver CheckboxButton må ha en label som forklarer hva alternativet er
- Konkret feilmelding:
errorMessageviser feilen, men teksten er ditt ansvar - Vurder
disabledmed omtanke. Et deaktivert alternativ er ofte vanskelig å forstå - Bruk checkbox kun for uavhengige valg. Er valgene gjensidig utelukkende, bruk RadioGroup
Hva komponenten gjør automatisk
Når du bruker <ix-checkbox-group> eller React-komponenten, settes dette opp for deg:
role="group"på containeren slik at skjermlesere annonserer gruppen riktig (det finnes ingen egen «checkboxgroup»-rolle)aria-labelledbytil legend-elementet: gruppens tilgjengelige navnaria-describedbytil description og error: leses etter legendaria-live="polite"på error-elementet slik at endringer kunngjøres uten å avbrytearia-invalidpå containeren synkroniseres med error-innholdet via MutationObserverhtmlFor/idmellom hver label og input: klikk på label toggler alternativet- Felles
namepropageres til alle inputs når du setternamepå gruppen, slik at alle valgene sendes med i skjemaet disabled/readonlypropagerer fra container til alle inputs (readonly blokkerer Space via tastatur, sidenreadOnlyer en no-op på checkbox)
Tastaturnavigasjon
| Tast | Handling |
|---|---|
| Tab | Flytter fokus til neste checkbox i gruppen |
| Shift+Tab | Flytter fokus til forrige checkbox |
| Space | Toggler valgt tilstand på checkboxen som har fokus |
Skjermleser
- Ved fokus inn i gruppen: "[legend-tekst], gruppe"
- Ved fokus på en checkbox: "[label], avkryssingsboks, [avkrysset/ikke avkrysset]"
- Når description er satt: leses opp etter legend som del av gruppe-konteksten
- Indeterminate: "[label], avkryssingsboks, delvis avkrysset"
- Ved feiltilstand: aria-invalid annonseres som «ugyldig», og feilmeldingsteksten leses opp polite via aria-live
WCAG-kriterier
Sist gjennomgått: 2026-06-29 — alle 56 WCAG 2.2-kriterier vurdert
WCAG-kriterier8 ditt ansvar · 14 håndtert · 38 ikke relevant · 0 ikke på plass
Ditt ansvar (8)
| Kriterium | Nivå | Hva du må gjøre |
|---|---|---|
| 1.3.1 Informasjon og relasjoner | A | Skriv beskrivende legend for gruppen. Legend forklarer hva brukeren skal velge mellom. Skjermlesere leser legend som gruppens tilgjengelige navn. "Hvordan vil du bli kontaktet?" er bedre enn "Kontakt". Du kan skjule legend visuelt med hideLegend, men den må fortsatt være meningsfull — den leses opp av skjermlesere. |
| 2.4.6 Overskrifter og ledetekster | AA | Skriv beskrivende legend for gruppen. Legend forklarer hva brukeren skal velge mellom. Skjermlesere leser legend som gruppens tilgjengelige navn. "Hvordan vil du bli kontaktet?" er bedre enn "Kontakt". Du kan skjule legend visuelt med hideLegend, men den må fortsatt være meningsfull — den leses opp av skjermlesere. |
| 3.3.2 Ledetekster eller instruksjoner | A | Skriv beskrivende legend for gruppen. Legend forklarer hva brukeren skal velge mellom. Skjermlesere leser legend som gruppens tilgjengelige navn. "Hvordan vil du bli kontaktet?" er bedre enn "Kontakt". Du kan skjule legend visuelt med hideLegend, men den må fortsatt være meningsfull — den leses opp av skjermlesere. |
| 3.3.2 Ledetekster eller instruksjoner | A | Skriv beskrivende label på hver CheckboxButton. Labelen skal beskrive hva alternativet er, ikke hva brukeren skal gjøre. "E-post" er bedre enn "Velg e-post". Hold labelen kort og presis — utfyllende forklaringer hører hjemme i description-propen. |
| 3.3.1 Identifikasjon av feil | A | Skriv konkret feilmelding. errorMessage skal forklare hva brukeren må gjøre, ikke bare at noe er feil. "Du må velge minst ett alternativ" er bedre enn "Påkrevd felt". Komponenten viser meldingen og setter aria-invalid på gruppen automatisk, men du skriver innholdet. |
| 3.3.3 Forslag ved feil | AA | Skriv konkret feilmelding. errorMessage skal forklare hva brukeren må gjøre, ikke bare at noe er feil. "Du må velge minst ett alternativ" er bedre enn "Påkrevd felt". Komponenten viser meldingen og setter aria-invalid på gruppen automatisk, men du skriver innholdet. |
| 3.3.2 Ledetekster eller instruksjoner | A | Vurder bruk av disabled. En deaktivert checkbox er vanskelig å forstå uten forklaring. Vurder om alternativet heller bør skjules, forklares eller presenteres som utilgjengelig på en tydeligere måte. Disabled bryter dessuten kontrastkravet (1.4.3 unntar disabled-elementer). |
| 3.3.2 Ledetekster eller instruksjoner | A | Bruk checkbox kun for uavhengige valg. Checkbox signaliserer at flere valg kan kombineres fritt. Er valgene gjensidig utelukkende (kun ett kan velges), bruk RadioGroup i stedet — ellers villeder du brukeren om hva som er mulig. |
Håndtert av komponenten (14)
| Kriterium | Nivå | Hva komponenten gjør |
|---|---|---|
| 1.3.1 Informasjon og relasjoner | A | ix-checkbox-group setter role="group", aria-labelledby til legend, og aria-describedby til description og error. Hver native input[type="checkbox"] kobles til sin label via for/id. |
| 1.4.1 Bruk av farge | A | Valgt tilstand vises både med hake (form) og endret farge — ikke kun farge. Indeterminate vises med strek. |
| 1.4.3 Kontrast (minimum) | AA | Tekst og indikator bruker --ix-color-foreground-main-default og --ix-color-fill-main-default. Forventes å oppfylle 4,5:1 mot standard bakgrunn. Verifiser ved egendefinerte bakgrunnsfarger. |
| 1.4.10 Omflyt | AA | Reflower korrekt ned til 320 px. Checkbox-gruppen vises som vertikal liste uten horisontal scroll. |
| 1.4.11 Kontrast for ikke-tekstlig innhold | AA | Checkbox-boksens border bruker --ix-color-border-main-default. Valgt/fokus/feil bruker --ix-color-fill-main-default eller --ix-color-fill-danger-default — forventes å oppfylle 3:1 mot bakgrunn. |
| 1.4.12 Tekstavstand | AA | Bruker --ix-font-size-md (relativ enhet) og tåler økt line-height, bokstav- og ordavstand uten tap av innhold. |
| 2.1.1 Tastatur | A | Native input[type="checkbox"] gir tastatur-tilgang gratis: Tab flytter fokus til hver checkbox, Space toggler valgt tilstand. Hver checkbox er et eget tab-stopp (ingen pil-navigasjon, i motsetning til radio). |
| 2.1.2 Ingen tastaturfelle | A | Fokus kan navigeres ut med Tab og Shift+Tab. Ingen tastaturfelle. |
| 2.4.7 Synlig fokus | AA | :focus-visible på input gir tydelig outline rundt boksen via CSS. |
| 2.5.8 Målstørrelse (minimum) | AA | Hver label har min-height som gjør klikkeflaten minst 24×24 px (WCAG 2.2 AA). Klikk på label toggler checkboxen. |
| 3.3.1 Identifikasjon av feil | A | ix-checkbox-group setter aria-invalid="true" på host når errorMessage har innhold, og kobler feilmeldingen via aria-describedby. |
| 3.3.3 Forslag ved feil | AA | errorMessage-propen brukes til å gi konkret feilmelding. Komponenten viser den, men teksten er konsumentens ansvar. |
| 4.1.2 Navn, rolle, verdi | A | Native input[type="checkbox"] gir rolle, navn (via label), checked-, indeterminate- og disabled-tilstand automatisk. role="group" på containeren grupperer dem. |
| 4.1.3 Statusmeldinger | AA | ix-checkbox-group setter aria-live="polite" på error-elementet slik at skjermlesere annonserer endringer i feilmeldingen uten å avbryte brukeren. |
Ikke relevant (38)
| Kriterium | Nivå | Hvorfor ikke relevant |
|---|---|---|
| 1.1.1 Ikke-tekstlig innhold | A | Hake-/strek-ikonet er dekorativt — tilstanden kommuniseres via checked/indeterminate. |
| 1.2.1 Bare lyd og bare video (forhåndsinnspilt) | A | Ingen medieelementer. |
| 1.2.2 Teksting (forhåndsinnspilt) | A | Ingen medieelementer. |
| 1.2.3 Synstolking eller mediealternativ (forhåndsinnspilt) | A | Ingen medieelementer. |
| 1.2.4 Teksting (direkte) | AA | Ingen medieelementer. |
| 1.2.5 Synstolking (forhåndsinnspilt) | AA | Ingen medieelementer. |
| 1.3.3 Sensoriske egenskaper | A | |
| 1.3.4 Visningsretning | AA | Ingen fast orientering — tilpasser seg visningsretning. |
| 1.3.5 Identifiser formål med inndata | AA | CheckboxGroup samler ikke standardiserte personopplysninger som dekkes av autocomplete-token. |
| 1.4.2 Styring av lyd | A | Ingen lydelementer. |
| 1.4.4 Endre tekststørrelse | AA | |
| 1.4.5 Bilder av tekst | AA | Ingen bilder av tekst. |
| 1.4.13 Innhold ved hover eller fokus | AA | |
| 2.1.4 Tastatursnarveier | A | Ingen egendefinerte tastatursnarveier. |
| 2.2.1 Justerbar hastighet | A | Ingen tidsbegrensede funksjoner. |
| 2.2.2 Pause, stopp, skjul | A | Ingen animasjon eller automatisk oppdatering. |
| 2.3.1 Terskelverdi på tre glimt | A | Ingen blinkende eller glimtende innhold. |
| 2.4.1 Hoppe over blokker | A | Sidekrav — gjelder ikke enkeltkomponenter. |
| 2.4.2 Sidetitler | A | Sidekrav — gjelder ikke enkeltkomponenter. |
| 2.4.3 Fokusrekkefølge | A | |
| 2.4.4 Formål med lenke (i kontekst) | A | Ingen lenker i komponenten. |
| 2.4.5 Flere måter | AA | Sidekrav — gjelder ikke enkeltkomponenter. |
| 2.4.11 Fokus ikke skjult (minimum) | AA | Ingen sticky/overlappende elementer som kan skjule fokus. |
| 2.5.1 Pekerbevegelser | A | Ingen drag-and-drop eller sveipebevegelser. |
| 2.5.2 Avbryt peker | A | |
| 2.5.4 Bevegelsesaktivering | A | Ingen bevegelsesbasert interaksjon. |
| 2.5.6 Samtidige inndatamekanismer | A | |
| 2.5.7 Drabevegelser | A | Ingen drag-and-drop. |
| 3.1.1 Språk på siden | A | Sidekrav — gjelder ikke enkeltkomponenter. |
| 3.1.2 Språk på deler av innhold | AA | Komponenten setter ikke lang-attributt — innhold er på sidespråket. |
| 3.2.1 Ved fokus | A | |
| 3.2.2 Ved inndata | A | |
| 3.2.3 Konsistent navigasjon | AA | Sidekrav — gjelder ikke enkeltkomponenter. |
| 3.2.4 Konsistent identifikasjon | AA | Systemkrav — gjelder konsistens på tvers av sider, ikke enkeltkomponenter. |
| 3.2.6 Konsistent hjelp | A | Sidekrav — gjelder plassering av hjelpefunksjon på tvers av sider. |
| 3.3.4 Forhindring av feil (juridisk, økonomisk, data) | AA | Flytkrav — gjelder bekreftelse/reversering av transaksjoner, ikke enkeltfelter. |
| 3.3.7 Redundant oppføring | A | Flytkrav — gjelder at brukeren ikke skal gjenta informasjon i en prosess. |
| 3.3.8 Tilgjengelig autentisering (minimum) | AA | Ikke en autentiseringskomponent. |
Props / API
CheckboxGroupProps
| Prop | Type | Påkrevd | Standard | Beskrivelse |
|---|---|---|---|---|
legend | string | Ja | Gruppens label. Vises og leses opp av skjermlesere | |
description | string | Nei | Hjelpetekst for hele gruppen | |
errorMessage | string | Nei | Feilmelding. Trigger aria-invalid automatisk når satt | |
name | string | Nei | name-attributtet på alle inputs. Propageres til hver input når satt | |
value | string[] | Nei | Kontrollert modus: hvilke alternativer som er valgt. Bruk sammen med onChange | |
defaultValue | string[] | Nei | [] | Ukontrollert modus: initielt valgte verdier. Brukeren kan endre fritt |
onChange | ChangeEventHandler<HTMLInputElement> | Nei | Event-basert. Kalles med det native change-eventet — toggl-verdien i event.target.value, av/på i event.target.checked. RHF samler de avmerkede verdiene til et string[]; i kontrollert bruk bygger du selv neste array. Lar {...register()} spres rett på | |
onBlur | FocusEventHandler<HTMLInputElement> | Nei | Videresendes til hver input (RHF touched-state ved mode: 'onBlur') | |
ref | Ref<HTMLInputElement> | Nei | Rutes ned på hver native checkbox-input. RHF akkumulerer dem og eier checked (register-modus) | |
disabled | boolean | Nei | false | Deaktiverer hele gruppen |
readOnly | boolean | Nei | false | Skrivebeskytter hele gruppen |
hideLegend | boolean | Nei | false | Skjuler legend visuelt — leses fortsatt av skjermlesere |
className | string | Nei | CSS-klasse på <ix-checkbox-group>-rotelementet | |
options | CheckboxOption[] | Nei* | Liste med alternativer. Snarvei for enkle lister — alternativ til children | |
children | ReactNode | Nei* | CheckboxButton-elementer. Brukes når du trenger mer kontroll enn options gir |
*Enten options eller children må være satt. Hvis begge er satt, vinner options.
I tillegg sendes øvrige HTML-attributter (id, tabIndex, role, aria-*, data-*, osv.) videre til <ix-checkbox-group>-rotelementet. Det er id + tabIndex={-1} som gjør at en feiloppsummering kan lenke til gruppen: rotelementet har role="group", så skjermleseren leser legend og feilmelding når fokus lander der.
<CheckboxGroup legend="Hvilke tjenester vil du ha?" id="tjenester" tabIndex={-1} … />
// og i feiloppsummeringen:
<a href="#tjenester">Velg minst én tjeneste</a>
To unntak:
aria-describedbykommer ikke gjennom.<ix-checkbox-group>eier den (den peker pådescriptionog feilmeldingen) og overskriver verdien du sender inn. Trenger du ekstra hjelpetekst, brukdescription.data-state,data-variant,data-size,disabledogreadonlykan ikke overstyres — de utledes av propene med samme navn.
CheckboxOption
| Felt | Type | Påkrevd | Beskrivelse |
|---|---|---|---|
value | string | Ja | Verdien som settes på input |
label | string | Ja | Synlig labeltekst |
CheckboxButtonProps
| Prop | Type | Påkrevd | Standard | Beskrivelse |
|---|---|---|---|---|
value | string | Ja | Verdien som settes på input. Identifiserer alternativet i gruppens value-array | |
label | string | Ja | Synlig labeltekst | |
disabled | boolean | Nei | false | Deaktiverer denne enkelt-knappen (kommer i tillegg til gruppe-disabled) |
className | string | Nei | CSS-klasse på wrapper-div | |
ref | Ref<HTMLInputElement> | Nei | Ref videresendes til <input>-elementet |
I tillegg støttes alle standard HTML input-attributter (name, id, autoFocus, defaultChecked, aria-*, osv.) som settes direkte på komponenten og sendes videre til <input>. value, type, size, children og onChange håndteres av komponenten.
CheckboxButton er laget for bruk inne i CheckboxGroup. Den har ingen onChange-prop, fordi gruppen håndterer endringene. Trenger du én enkeltstående checkbox, bruk Checkbox.
Tilpasning med CSS
Inni <ix-checkbox-group> styles <input type="checkbox"> og <label> (inni .ix-checkbox) automatisk. Indikatoren tegnes som pseudo-element på labelen, så du trenger ingen ekstra markup.
Tilgjengelige klasser og selektorer
| Element | Selektor |
|---|---|
| Gruppe-wrapper | .ix-checkbox-group (eller tagnavn ix-checkbox-group) |
| Legend | [data-field="legend"] |
| Description | [data-field="description"] |
| Items-container | [data-field="items"] |
| Checkbox-wrapper | .ix-checkbox |
| Input — visuelt skjult (valgfri hook) | .ix-checkbox__input |
| Label med indikator (valgfri hook) | .ix-checkbox__label |
| Feilmelding | [data-field="error"] |
| Skjult legend | .ix-sr-only |
Eksempel: bruk i egen HTML-struktur
Inni <ix-checkbox-group> kobler komponenten input og label automatisk, så du trenger ingen id eller for:
<ix-checkbox-group name="interesser">
<span data-field="legend">Velg interesser</span>
<div data-field="items">
<div class="ix-checkbox">
<input type="checkbox" value="sport" />
<label>Sport</label>
</div>
</div>
<span data-field="error"></span>
</ix-checkbox-group>
Relatert
- Checkbox — en enkeltstående checkbox
- Label — labeltekst for gruppen og for hvert alternativ
- RadioGroup — når kun ett alternativ kan velges
- ValidationMessage — feilmeldingsteksten
- Designvalg for CheckboxGroup — tekniske avveininger