Skip to main content

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

Laster...

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:

Laster...

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.

Laster...

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.

Laster...

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.

Laster...

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.

Laster...

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: errorMessage viser feilen, men teksten er ditt ansvar
  • Vurder disabled med 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-labelledby til legend-elementet: gruppens tilgjengelige navn
  • aria-describedby til description og error: leses etter legend
  • aria-live="polite" på error-elementet slik at endringer kunngjøres uten å avbryte
  • aria-invalid på containeren synkroniseres med error-innholdet via MutationObserver
  • htmlFor/id mellom hver label og input: klikk på label toggler alternativet
  • Felles name propageres til alle inputs når du setter name på gruppen, slik at alle valgene sendes med i skjemaet
  • disabled/readonly propagerer fra container til alle inputs (readonly blokkerer Space via tastatur, siden readOnly er en no-op på checkbox)

Tastaturnavigasjon

TastHandling
TabFlytter fokus til neste checkbox i gruppen
Shift+TabFlytter fokus til forrige checkbox
SpaceToggler 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)
KriteriumNivåHva du må gjøre
1.3.1 Informasjon og relasjonerASkriv 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 ledeteksterAASkriv 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 instruksjonerASkriv 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 instruksjonerASkriv 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 feilASkriv 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 feilAASkriv 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 instruksjonerAVurder 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 instruksjonerABruk 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)
KriteriumNivåHva komponenten gjør
1.3.1 Informasjon og relasjonerAix-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 fargeAValgt tilstand vises både med hake (form) og endret farge — ikke kun farge. Indeterminate vises med strek.
1.4.3 Kontrast (minimum)AATekst 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 OmflytAAReflower korrekt ned til 320 px. Checkbox-gruppen vises som vertikal liste uten horisontal scroll.
1.4.11 Kontrast for ikke-tekstlig innholdAACheckbox-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 TekstavstandAABruker --ix-font-size-md (relativ enhet) og tåler økt line-height, bokstav- og ordavstand uten tap av innhold.
2.1.1 TastaturANative 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 tastaturfelleAFokus kan navigeres ut med Tab og Shift+Tab. Ingen tastaturfelle.
2.4.7 Synlig fokusAA:focus-visible på input gir tydelig outline rundt boksen via CSS.
2.5.8 Målstørrelse (minimum)AAHver 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 feilAix-checkbox-group setter aria-invalid="true" på host når errorMessage har innhold, og kobler feilmeldingen via aria-describedby.
3.3.3 Forslag ved feilAAerrorMessage-propen brukes til å gi konkret feilmelding. Komponenten viser den, men teksten er konsumentens ansvar.
4.1.2 Navn, rolle, verdiANative input[type="checkbox"] gir rolle, navn (via label), checked-, indeterminate- og disabled-tilstand automatisk. role="group" på containeren grupperer dem.
4.1.3 StatusmeldingerAAix-checkbox-group setter aria-live="polite" på error-elementet slik at skjermlesere annonserer endringer i feilmeldingen uten å avbryte brukeren.
Ikke relevant (38)
KriteriumNivåHvorfor ikke relevant
1.1.1 Ikke-tekstlig innholdAHake-/strek-ikonet er dekorativt — tilstanden kommuniseres via checked/indeterminate.
1.2.1 Bare lyd og bare video (forhåndsinnspilt)AIngen medieelementer.
1.2.2 Teksting (forhåndsinnspilt)AIngen medieelementer.
1.2.3 Synstolking eller mediealternativ (forhåndsinnspilt)AIngen medieelementer.
1.2.4 Teksting (direkte)AAIngen medieelementer.
1.2.5 Synstolking (forhåndsinnspilt)AAIngen medieelementer.
1.3.3 Sensoriske egenskaperA
1.3.4 VisningsretningAAIngen fast orientering — tilpasser seg visningsretning.
1.3.5 Identifiser formål med inndataAACheckboxGroup samler ikke standardiserte personopplysninger som dekkes av autocomplete-token.
1.4.2 Styring av lydAIngen lydelementer.
1.4.4 Endre tekststørrelseAA
1.4.5 Bilder av tekstAAIngen bilder av tekst.
1.4.13 Innhold ved hover eller fokusAA
2.1.4 TastatursnarveierAIngen egendefinerte tastatursnarveier.
2.2.1 Justerbar hastighetAIngen tidsbegrensede funksjoner.
2.2.2 Pause, stopp, skjulAIngen animasjon eller automatisk oppdatering.
2.3.1 Terskelverdi på tre glimtAIngen blinkende eller glimtende innhold.
2.4.1 Hoppe over blokkerASidekrav — gjelder ikke enkeltkomponenter.
2.4.2 SidetitlerASidekrav — gjelder ikke enkeltkomponenter.
2.4.3 FokusrekkefølgeA
2.4.4 Formål med lenke (i kontekst)AIngen lenker i komponenten.
2.4.5 Flere måterAASidekrav — gjelder ikke enkeltkomponenter.
2.4.11 Fokus ikke skjult (minimum)AAIngen sticky/overlappende elementer som kan skjule fokus.
2.5.1 PekerbevegelserAIngen drag-and-drop eller sveipebevegelser.
2.5.2 Avbryt pekerA
2.5.4 BevegelsesaktiveringAIngen bevegelsesbasert interaksjon.
2.5.6 Samtidige inndatamekanismerA
2.5.7 DrabevegelserAIngen drag-and-drop.
3.1.1 Språk på sidenASidekrav — gjelder ikke enkeltkomponenter.
3.1.2 Språk på deler av innholdAAKomponenten setter ikke lang-attributt — innhold er på sidespråket.
3.2.1 Ved fokusA
3.2.2 Ved inndataA
3.2.3 Konsistent navigasjonAASidekrav — gjelder ikke enkeltkomponenter.
3.2.4 Konsistent identifikasjonAASystemkrav — gjelder konsistens på tvers av sider, ikke enkeltkomponenter.
3.2.6 Konsistent hjelpASidekrav — gjelder plassering av hjelpefunksjon på tvers av sider.
3.3.4 Forhindring av feil (juridisk, økonomisk, data)AAFlytkrav — gjelder bekreftelse/reversering av transaksjoner, ikke enkeltfelter.
3.3.7 Redundant oppføringAFlytkrav — gjelder at brukeren ikke skal gjenta informasjon i en prosess.
3.3.8 Tilgjengelig autentisering (minimum)AAIkke en autentiseringskomponent.

Props / API

CheckboxGroupProps

PropTypePåkrevdStandardBeskrivelse
legendstringJaGruppens label. Vises og leses opp av skjermlesere
descriptionstringNeiHjelpetekst for hele gruppen
errorMessagestringNeiFeilmelding. Trigger aria-invalid automatisk når satt
namestringNeiname-attributtet på alle inputs. Propageres til hver input når satt
valuestring[]NeiKontrollert modus: hvilke alternativer som er valgt. Bruk sammen med onChange
defaultValuestring[]Nei[]Ukontrollert modus: initielt valgte verdier. Brukeren kan endre fritt
onChangeChangeEventHandler<HTMLInputElement>NeiEvent-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å
onBlurFocusEventHandler<HTMLInputElement>NeiVideresendes til hver input (RHF touched-state ved mode: 'onBlur')
refRef<HTMLInputElement>NeiRutes ned på hver native checkbox-input. RHF akkumulerer dem og eier checked (register-modus)
disabledbooleanNeifalseDeaktiverer hele gruppen
readOnlybooleanNeifalseSkrivebeskytter hele gruppen
hideLegendbooleanNeifalseSkjuler legend visuelt — leses fortsatt av skjermlesere
classNamestringNeiCSS-klasse på <ix-checkbox-group>-rotelementet
optionsCheckboxOption[]Nei*Liste med alternativer. Snarvei for enkle lister — alternativ til children
childrenReactNodeNei*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-describedby kommer ikke gjennom. <ix-checkbox-group> eier den (den peker på description og feilmeldingen) og overskriver verdien du sender inn. Trenger du ekstra hjelpetekst, bruk description.
  • data-state, data-variant, data-size, disabled og readonly kan ikke overstyres — de utledes av propene med samme navn.

CheckboxOption

FeltTypePåkrevdBeskrivelse
valuestringJaVerdien som settes på input
labelstringJaSynlig labeltekst

CheckboxButtonProps

PropTypePåkrevdStandardBeskrivelse
valuestringJaVerdien som settes på input. Identifiserer alternativet i gruppens value-array
labelstringJaSynlig labeltekst
disabledbooleanNeifalseDeaktiverer denne enkelt-knappen (kommer i tillegg til gruppe-disabled)
classNamestringNeiCSS-klasse på wrapper-div
refRef<HTMLInputElement>NeiRef 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

ElementSelektor
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