v6.14 (Aug 2024)
Combobox: onChange
er endret til å motta den nye verdien som første og eneste parameter, i stedet for event. Med andre ord må onChange={(event) => setState(event.target.value)}
endres til onChange={setState}
eller tilsvarende. (Endringen er gjort utenom en major-version siden komponenten har UNSAFE-prefix.)
v6.0 (Feb 2024)
Fokuset til versjon 6 er å modernisere module-resolution, samt forberede løsningene våre til en fremtidig verden der RSC er standard.
"use client"
For mer informasjon kan du lese guide for Aksel + Nextjs.
Komponenter fra @navikt/ds-react
og ikoner fra @navikt/aksel-icons
setter nå "use client"
selv. Komponentene regnes da som Client Components i Next.js, som gjør at brukere av Next.js "App Router" kan bruke dem rett ut av boksen. Et unntak til dette er komponenter med dot-notasjon som ikke fungerer i server-components. Se guide for Aksel + Nextjs for hvordan du løser dette.
Bundle size
En konsekvens av oppdateringen er at Next.js ikke klarer å tree-shake react- og ikonpakke riktig lengre. Dette er et kjent problem med Next.js, men kan løses ved å bruke optimizePackageImports. Obs! Dette vil kreve nextjs >= v13.5.
Uten dette skal endringen i praksis ikke kunne brekke noe, men eldre bundlere og rammeverk kan gi warnings.
Module resolution
React- og ikonpakke har fått oppdatert package entrypoints fra gammel module/main syntax til moderne exports. Exports ble introdusert i Node.js 14, så alle moderne bundlere og frameworks skal støtte dette. Oppdateringen av entrypoints gjør også at det ikke lengre er mulig å importere komponenter fra annen path enn @navikt/ds-react
. Custom-import som @navikt/ds-react/cjs/button/Button.js
vil ikke fungere.
Hvis du har brukt denne typen import for å hente ut funksjonalitet eller props og dette brekker nå, ta kontakt så undersøker vi nærmere.
ES modules
Pakkene har nå ekte ES modules (ESM)-støtte. Dette gjør at Astro node kan bruke dem uten problemer.
For at dette skulle være mulig har vi oppdatert major-versjon for 2 dependencies:
Hvis du bruker noen av disse i løsningen din, anbefaler vi å oppdatere til samme major-versjon. Du unngår da dobbel lasting av date-fns
som raskt kan øke bundle-size med over 25 kB.
OverridableComponent
Vi har rullet tilbake en tidligere endring fordi den viste seg å tillate vilkårlige props på komponenter som bruker OverridableComponent
, når man ikke brukte as
-propen.
Endringen skulle gjøre det enklere å lage egene implementasjoner/wrapper-koponenter rundt Aksel-komponenter. Hvis dere har gjort dette og nå får type-feil, kan dere prøve en av disse variantene:
DatePicker, MonthPicker
openOnFocus
-prop er fjernet.
Chat
Propene backgroundColor
og avatarBgColor
er fjernet. Bruk variant
som erstatning. Hvis disse ikke fungerer tilbys det tokens som kan overskrives.
Modal
Prop-typene er gjort strengere for å gjøre det lettere å gjøre rett, primært for å unngå at onBeforeClose
brukes når man egentlig burde brukt onClose
.
Grid
Gammel Grid-komponent er fjernet. Alle klasser med .navds-grid
-prefix er fjernet. Se HGrid for moderne grid-komponent.
ContentContainer
Se Page for ekvivalent komponent.
width="xl"
er nærmeste bredde til ContentContainer
Table
SortState.direction har nå "none"
tilgjengelig som gir lettere type-håndtering.
Search
Du vil nå få type-feil hvis du prøver å sette type
. Internt i komponenten er type
hardkodet til "search" og det har aldri vært mulig å endre dette med en prop.
Tokens
z-index
Fjernet --a-z-index-modal
-token da systemet nå bruker native dialog
-element. Dette vil også påvirke brukere av z-modal
i tailwind.
Breakpoint
Nytt brekkpunkt for 1440px --a-breakpoint-2xl
. Alle primitives støtter også nå 2xl-brekkpunkt for responsive props.
For brukere av tailwind-config vil dette si at screen
er oppdatert. Dette vil overskrive default tailwind-config som er 1536px
til å nå være 1440px
.
Action-farger
Som konsekvens ved oppdatering av action-farger brukt på ulike komponenter har flere komponenter fått nye tokens. Dette vil bare være en breaking-change hvis du manuelt har overstyrt disse gjennom komponent-tokens. For alle endringer kan man se github-diff.
v5.0 (Aug 2023)
Modal er skrevet om til å bruke native dialog i stedet for react-modal. Prop appElement
er også fjernet fra Provider da den ikke vil ha noen funksjon lengre.
React
CSS
v5.3.1
Klassene navds-guide__illustration
, navds-guide__illustration--small
og navds-guide__illustration--medium
er fjernet.
v4.0 (Juli 2023)
Estimert migreringstid: ~5 minutter. Release-notes.
Dropdown, Timeline og InternalHeader (tidligere Header) er flyttet til @navikt/ds-react
. Tilhørende styling er flyttet fra @navikt/ds-css-internal
til @navikt/ds-css
.
DatePicker og MonthPicker er også ute av Beta. Dette vil si at UNSAFE_
-prefix er fjernet fra komponentene.
Migrering Internal til Core
Om du ikke ønsker å gjøre denne migreringen nå, vil disse pakkene fortsatt være tilgjengelig på versjon 3.x.x. Men for å få fremtidige oppdateringer anbefaler vi å oppdatere. Vi kan ikke garantere kompatibilitet mellom ds-css
v4 og ds-css-internal
v3 på sikt.
Migrering DatePicker/Monthpicker
v3.0 (Mai 2023)
Oppdateringen vil ikke brekke noe i de fleste løsninger!
Hvis du har manuelt overskrevet styling for Stepper.Step
, HelpText
eller Accordion
bør du sjekke om disse fortsatt fungerer som ønsket.
v2.7: Ny ikonpakke
Vår nye ikonpakke, @navikt/aksel-icons
, bruker samme API som den tidligere løsningen @navikt/ds-icons
. For en enklere migrering kan du fortsatt benytte begge pakkene inntil du har fullført overgangen til den nye ikonpakken. Du kan lese mer om ikonpakken i blogginnlegget vårt eller besøke de nye ikonsidene.
De fleste ikonene vil være nesten identiske, men det kan forekomme noen visuelle justeringer. Derfor er det viktig å utføre en enkel sjekk for å sikre at alt stemmer under migreringen. Du kan også finne den gamle ikonoversikten for å sammenligne under migreringen.
v2: Tokens oppdatering og Font-lasting (Nov 2022)
I versjon 2.0.0 har vi hatt fokus på tokens, semantiske farger og optimalisering av font-lasting.
Tokens
Målet for token-oppdateringen er å legge til rette for mer fart og flyt både i design og utviklingsfasen av løsninger. Vi har gjort en revisjon av semantikk og navngiving for tokens som vi håper vil gjøre det lettere å bruke dem aktivt i løsningene.
Codemod
Det er laget codemods for alle token-endringer i CSS, sass, less og js-format. Finner mer informasjon om disse i codemod-readme. For de fleste vil migreringen til nye tokens kunne gjøres på noen minutter.
For brukere av tailwind-pakken vår blir dette dessverre en litt mer manuell prosess. Ved migrering av tailwind-tokens brukt på aksel.nav.no tok denne prosessen ~15 minutter.
Breakpoints
For brukere av tailwind-pakken har nå ds-tailwind en screen
-preset. Dette vil bare påvirke de som har brukt sm
: størrelse som blir endret fra 686px (tailwind-default) -> 480px
Prefiks
Vi har valgt å gå bort fra --navds
, --navds-global-color
og --navds-semantic-color
prefiksene. Alle tokens har nå prefiks --a
.
Endringer
Utenom endring i prefikser, er det bare semantiske farger som er påvirket av endringer i navn. Vi anbefaler å ta i bruk codemod-løsningen for oppdateringen, men tailwind-brukere kan bruke oversikten under.
Obs!! border-divider
har nå alpha-verdi! Kan derfor være lurt å dobbelsjekke at dette fortsatt ser riktig ut i din løsning hvis du tidligere brukte divider
.
Komponent-tokens og overskriving av tokens
Vi har oppdatert hvordan vi håndterer komponent-spesifikke tokens. Du vil ikke lengre kunne bruke eks --navds-button-color-primary-text
til å style din egen kode eller gjøre overskrivinger. Du kan lese mer om den nye løsningen i "Tokens i kode".
Instansene der du har brukt komponent-tokens for å style din egen kode, vil automatisk bli oppdatert til ny semantisk verdi med codemod.
For de som har overskrevet tokens vil dette ikke lengre fungere som før og vi ønsker at alle tar egne valg for hvordan de håndterer dette. Ved kjøring av codemod vil derfor alle instansene med overskrevet designsystem-token bli prefikset med --v2-migration
slik at du selv kan gjøre en CTRL + F
og oppdatere dem.
Fonter
NAV har endelig en egen CDN løsning! Etter et supert initiativ fra frontend-platform har vi nå kunnet hoste våre egne font-filer. Ved oppdatering til v2 vil styling levert gjennom @navikt/ds-css
gå fra 196kB til 96kB (uten gzip). I praktisk test med nextjs build ble css-bundle 78kB mindre!
For mange vil dette bare "funke", men er noen grep som må gjøres for å sikre at dette fungerer som ønsket for alle.
Oppdatere CSP (content security policy)
Hvis du har satt opp en CSP i løsningen din, kan det hende du må oppdatere den for å tillate lasting fra cdn.nav.no. Kan lese mer om font-src på mdn.
Preload
Vi setter font-display: swap
, som tilsier at en fallback-font vil bli lastet når man ikke får tak i ønsket font raskt nok. For å unngå FOUT anbefaler vi at man legger til en link-tag med preload i document-head. Kan lese mer om dette i denne web-dev demoen.
Vi har også valgt å bruke den oppdaterte versjonen av Source Sans Pro, som nå heter Source Sans 3. I kode importeres den fortsatt som font-family:"Source Sans Pro"
slik at den fortsatt er bakoverkompatibel, og ikke vil være noe man trenger å oppdatere selv.
Beta til v1
Designsystemet er endelig ute av Beta! Og med det kommer det noen breaking changes som vi forklarer litt her.
Samversjonering
Med v1-release er alle pakkene samversjonerte. Dette vil si alle pakker har samme versjon, uansett om siste release kun endret på én av pakkene. Bruker du ds-css v1.1.0, bør du også bruke ds-react v1.1.0.
Codemod
Breaking changes er kjedelige, noe vi er veldig klare over. Vi har derfor prøvd oss på en codemod-pakke (@navikt/ds-codemod
) som kan gjøre migrering til nyere versjoner litt lettere. Noen breaking changes i komponenter vil du kunne fikse via @navikt/ds-codemod
, andre må gjøres selv. Vi anbefaler å sjekke alle komponenter som berører deg fra listen under. Du finner en codemod README på Github, i Designsystemet-repoet.
Breaking changes
Accordion og ReadMore (❌ ikke codemod)
renderContentWhenClosed
-prop er fjernet fra begge komponentene. Normal oppførsel er nå alltid å ha innholdet i dom-en. Dette vil la f.eks. Google indeksere innholdet bedre, og det er en bedre uu-praksis fordi react-collapse hadde noen uu-bugs. Vi har ikke laget noen codemods for dette og anbefaler alle å dobbelsjekke at alt funker som forventet når du gjør denne endringen.
Komponentene bruker heller ikke pakken "react-collapse" lengre. Dette vil bare påvirke deg om du manuelt overskriver styling på klassene ReactCollapse--collapse
og ReactCollapse--content
.
Button (❌ ikke codemod)
Nye props
Bruk av ikoner i knapp er nå endret, så alle som i dag bruker ikoner i <Button />
må oppdatere koden sin. Endingen er gjort for å ha mer kontroll på rendring av ikon og plasseringen i selve knappen.
Tabs (✅ codemod)
SpeechBubble heter nå Chat (🟡 delvis codemod, se under)
SpeechBubble og SpeechBubble.Bubble endrer navn til Chat og Chat.Bubble. Codemod tar seg av renamingen.
Pagination (✅ codemod)
Komponenten var tidligere bare tilpasset interne-flater og brøt vår egen konvensjon på sizing da medium
bare var 32x32px. Vi har derfor forslkjøvet sizing-skalaen og lagt til en versjon tilpasset eksterne flater.
På grunn av hvordan flyttingen av sizing-skalaen fungerer er det ikke mulig å kjøre codemod flere ganger uten at størrelsen blir nedjustert hver gang. Derfor blir det automatisk satt en prop data-version="v1"
som codemoden bruker som filter. Denne kan beholdes eller fjernes etter migrering ettersom hva man ønsker.
Popover/Helptext (❌ ikke codemod)
Vi har migrert til et nytt "floating"-api og bruker ikke "react-popper" eller "popperjs" lenger. For deg som bruker vil dette forhåpentligvis ikke ha noen uventede effekter, men placement auto
, auto-start
og auto-end
er ikke lengre tilgjengelig. Vi fant ingen som eksplisitt hadde satt dette, så vi laget ikke en codemod for dette.
CopyToClipboard (❌ ikke codemod)
iconPlacement
-prop er renamet til iconPosition
. Har nå samme navn som eks Button og Tabs.Tab. Vi har fokusert på codemods til core-pakken og har ikke laget en codemod til denne
ConfirmationPanel (❌ ikke codemod)
Ref er flyttet fra wrapper (div) til checkbox (input). Vil bare påvirke brukere av ref
-prop
StepIndicator blir Stepper (❌ ikke codemod)
Se mer info under Deprecation
Deprecation
I systemet vårt har vi nå flere komponenter som ble laget og lagt til i designsystemet med fokus på hurtighet heller enn langsiktighet. Fordi vi setter et større fokus på stabilitet ønsker vi samtidig å avvikle forvalting av noen komponenter.
Vi kan f.eks. velge å avvikle forvaltning av komponenten når vi erstatter en komponent med en annen, når en komponent ikke har blitt oppdatert på lenge eller når komponenten fremdeles er i beta/er ustabil. Vi håper å gjøre migreringen lettest mulig.
MicroCard
Denne komponenten blir i dag brukt på nav.no sine sidemaler, men med et nyere og mer oppdatert design. Etterhvert håper vi at vi kan gjøre det lettere å ta i bruk kompoentene brukt på sidemalene, men for nå ønsker vi ikke å forvalte utdaterte komponenter som dette i koden vår.
Legger ved lenke til koden hvis man vil kopiere den inn i lokalt prosjekt: Css og React (overridablecomponent kan her erstattes med en <a>-tag eller tilsvarende)
PageHeader
Avvikles av samme grunn som MicroCard
Lenke til koden her: Css og React.
Menu
Avvikles av samme grunn som MicroCard
Lenke til koden her: Css og React.
StepIndicator
Komponenten erstattes med Stepper
som finnes i både horisontal og vertikal versjon. På grunn av API-endring i hva activeElement
er, har vi valgt å ikke lage en codemod for denne. Endringene du som utvikler og bruker av kompontenten må gjøre er:
Divider
@navikt/ds-react-internal sin <Divider />
komponent heter nå <Dropdown.Menu.Divider />
.
Misc
For å forminske "bloating" har vi kvittet oss med flere unødvendige dependencies. Vi håper det vil bli lettere å ta i bruk Designsystemet for de som f.eks bruker skypack eller lignende verktøy. Vi har en del å gå på for å optimalisere pakkene, men er et steg i riktig retning.
Noen av endringene kan påvirke løsningen deres hvis dere ikke selv har lagt til imports, men bruker dem via ds-react pakken. Dette anbefaler vi ikke, men antar yarn/npm eller build-step sier ifra hvis dette er tilfellet.
Endringer i dependencies:
nav-frontend pakker
Vi har valgt å ikke støtte nav-frontend pakkene fremover og håper de fleste vil velge å bruke de nye løsningene våre for fremtidige prosjekt eller refaktoreringer.
For deg som vil oppdatere prosjektet ditt til det nye designsystemet vil det dessverre kunne bli en del arbeid basert på hvor mye av det gamle du har brukt. En god start er å ta en titt på "kom i gang som utvikler"-artikkelen som forklarer hvordan de nye løsningene tas i bruk.
Noen tekniske fordeler med bruk av de nye løsningene for deg som utvikler er
Generelle API-endringer
De fleste komponentene har fått oppdatert API-et sitt. Ved oppdaterting fra gammel til ny komponent kan det være lurt å ta en titt på props-seksjonene da eksemplene under ikke vil dekke alle endringene.
Størrelser
I nav-frontend brukte flere komponenter propnavnene type, kompakt og mini for diverse padding/margin/typo endringer. I de nye pakkene vil størrelser settes konsekvent med size. size="small"
er ofte ment for interne flater og vi spesielt for interaktive komponenter anbefaler vi å bruke size="medium"
.
Varianter
For komponenter med visuelle varianter ble type
ofte brukt. Nå vil vi prøve å konsekvent bruke variant
for disse tilfellene.
Skjemaelementer
RadioGroup og CheckboxGroup kan nå selv styre checked-state for input-elementene med value
og tilhørende onChange
-prop. Du trenger da ikke lengre å sette checked true/false på hvert av Checkbox/Radio-elementene med tilhørende logikk.
feil + feilId
er endret til error + errorId
for alle skjemaelementer. Error id settes også nå på aria-describedby ovenfor aria-errormessage, da sistnevnte ikke har så god skjermleserstøtte.
Alertstripe (✅ Alert)
Bekreftcheckbokspanel (✅ ConfirmationPanel)
inputProps
er fjernet, "rest"-props blir nå satt direkte på input-elementet i ConfirmationPanel
Checkbokspanelgruppe ❌
Vi har valgt å ikke ta med CheckboksPanel og CheckboksPanelGruppe inn i nye løsninger.
Checkboks (✅ Checkbox)
State kan lettere håndteres med hjelp av onChange og value i CheckboxGroup nå.
Chevron ❌
Chevron er nå et ikon i @navikt/ds-icons
-pakken. Finner variantene i ikonsøket vårt under "chevron".
Ekspanderbartpanel (🟡 Accordion)
Accordion er ment som erstattning for Ekspanderbartpanel. Bruk og funksjonalitet er litt endret på, så anbefaler å referer til dokumentasjonen når du migrerer.
Vi er klar over at Accordion ikke dekker helt den samme bruken som Ekspanderbartpanel og har det på todo-lista å få sett på det.
Etikett (✅ Tag)
Feiloppsummering (✅ ErrorSummary)
FnrInput ❌
Vi har ikke tatt denne med videre i pakkene våre. Kan bruk vår TextField-komponent og NAVs fnr-valideringspakke (github.com/navikt/fnrvalidator)
Hjelpetekst (✅ HelpText)
Ikonknapper ❌
Vi har ikke lengre noen knapper med ikon-preset. Kan replikeres med hjelp av ikonpakken vår @navikt/ds-icons
.
Input (✅ TextField)
Vi har ikke lengre en egen bredde-prop. Bruke heller native input-prop size
eller styling.
Knapp (✅ Button)
Lenke (✅ Link)
Lenkepanel (✅ LinkPanel)
Lesmerpanel ❌
Vi har ikke tatt med denne komponenten inn i de nye pakkene, kan se om alternativene under fungerer som erstatning.
Lukknapp ❌
Se over på "Knapp".
Modal (✅ Modal)
Har nå en egen komponent Modal.Content som legger på en default-padding.
Panel (✅ Panel)
Popover (✅ Popover)
Har nå en egen komponent Popover.Content som legger på en default-padding.
Radio (✅ Radio)
RadioPanelGruppe ❌
Vi har valgt å ikke ta med RadioPanelGruppe inn i nye løsninger.
Select (✅ Select)
Se dokumentasjon for API-endringer.
Skjemagruppe (🟡 Fieldset)
Vi har en egen generell Fieldset-komponent i systemet, men har valgt å ikke dokumentere denne da den er mest ment for internt bruk.
Snakkeboble (✅ Chat)
Spinner (✅ Loader)
Stegindikator (✅ Stepper)
Tabell (✅ Table)
Table er nå en egen react-komponent. Sjekk ut dokumentasjonen for å se hvordan du kan erstatte din tabell med en komponenten.
Tabs (✅ Tabs)
Tabs har nå fått tabpanel integrert i komponenten.
Tekstomrade ❌
Vi har ikke denne komponenten med inn i de nye pakkene. Du kan finne parser-pakken ble brukt for denne løsningen på github.
Textarea (✅ Textarea)
ToggleGruppe/ToggleKnapp (🟡 ToggleGroup)
Veileder ❌
Vi har ikke denne komponenten med i de ny pakkene. Som erstatter tenker vi GuidePanel nevnt under.
Veilederpanel (✅ GuidePanel)
nav-frontend-typografi til V1
Ikke alle typografikomponentene i @navikt/ds-react
er én-til-én med de i nav-frontend-typografi
, så så vi foreslår at du spør en designer om du er usikker på hvilken komponent du skal velge. Du kan også spørre en av oss i Designsystemet (#designsystemet i Slack).
Tekststørrelse og heading-nivå
Overskrifters tekststørrelse er nå uavhengig av heading-nivået. Det betyr at du står fritt til å sørge for at overskrift-hierarkiet stemmer for din nettside, uavhengig av visuelt hierarki. Før kunne det være trøblete om men f.eks. ønsket seg en h1, men <Sidetittel>
opplevdes som for stor.
En direkte oversettelse fra gamle til nye komponenter, hvor man bevarer størrelsene, ser sånn ut:
Brødtekst
De nye komponentene for brødtekst heter <BodyLong>
og <BodyShort>
. Altså blir <Normaltekst>
i stedet til <BodyLong>
/<BodyShort>
.
<BodyLong>
er ment å brukes der det er snakk om løpende tekst, f.eks. i en artikkel. I situasjoner der teksten med fordel kan være mer kompakt skal <BodyShort>
brukes, for den har en lavere linjehøyde.
Ny brødtekst-størrelse er 18px. Om du bygger/vedlikeholder grensesnitt med kompakt design (les; interne flater) og ønsker å fortsette å bruke 16px brødtekst, så kan du bruke <BodyLong size="small">
og <BodyShort size="small">
.