v5.0
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
- Hvis du bruker
Provider
må du sjekke og ev. fjerneappElement
-propen. - Fjern kall til
Modal.setAppElement()
- Søk og erstatt "Modal.Content" med "Modal.Body"
- Modalen rendres ikke lenger som en portal. Sjekk at du ikke nester elementer som ikke kan nestes (feks.
<form>
). Hvis du er avhengig av at modalen rendres som en portal, kan du bruke prop-enportal
. - Oppdatere props på
<Modal>
:onClose
trigges nå etter at modalen er lukket (ikke før), samt uansett om den lukkes med Esc, lukkeknapp,open={false}
ellerclose()
. Dette er native oppførsel. Når du oppdaterer lokalopen
state her bør du derfor brukefalse
eksplisitt i stedet for!open
eller lignende.
Hvis du har logikk her som skal hindre at modalen kan lukkes (feks. skjemavalidering) må dette flyttes tilonBeforeClose
.shouldCloseOnEsc
er fjernet. (Standard oppførsel er at du kan lukke med Esc, men det kan ev. hindres slik:onCancel={(e) => e.preventDefault()}
.)shouldCloseOnOverlayClick
er fjernet. (Standard oppførsel er at klikk utenfor modalen ikke har noen effekt.)parentSelector
er fjernetoverlayClassName
er fjernet. Les mer om CSS under.closeButton
er flyttet til headeren. For å få lukkeknapp (X) øverst til høyre må du legge til en header (se dokumentasjonen).
- Legg eventuelt til header og footer. Dette er ikke påkrevet for at modalen skal virke, men er anbefalt. Det er spesielt anbefalt med header siden det gir deg lukkeknapp. Se dokumentasjonen for mer informasjon og eksempler.
CSS
- Klassen
navds-modal__overlay
er ikke lenger i bruk. For å endre farge kan du bruke token:::backdrop { --ac-modal-backdrop: white; }
. For annen styling kan du bruke.navds-modal::backdrop
og.navds-modal--polyfilled + .backdrop
. - Klassen
navds-modal__button--shake
er ikke lenger i bruk - Klassen
ReactModal__Body--open
har endret navn tilnavds-modal__document-body
. Denne klassen tilhørte pakken react-modal, som ikke lenger brukes. (Hvis dere har brukt denne pakken selv, i tillegg til modal-komponenten i Aksel, må dere kanskje benytte begge klassene.)
v5.3.1
Klassene navds-guide__illustration
, navds-guide__illustration--small
og navds-guide__illustration--medium
er fjernet.
v4.0
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
- Endre import fra
@navikt/ds-react-internal
til@navikt/ds-react
(codemod:v4-internal-react
) - Rename Header til InternalHeader (codemod:
v4-internal-react
) - Fikse overskrevne klassenavn:
navdsi
-prefix tilnavds
-prefix. (codemod:v4-internal-css
) - Fikse tokens fra header: --ac-header til --ac-internalheader (codemod:
v4-internal-css
) - Fjerne import av
@navikt/ds-css-internal
stylesheet - Opprydding: Fjerne
@navikt/ds-react-internal
og@navikt/ds-css-internal
frapackage.json
-depdendencies.
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
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
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
icon
: Ikon som rendres i knappiconPosition
: Om ikonet skal være venstre/høyrestilt
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)
loop
er flyttet fraTabs.Tablist
tilTabs
(codemod fikser)iconPosition
er flyttet fraTabs.Tab
tilTabs
(codemod fikser)
SpeechBubble heter nå Chat (🟡 delvis codemod, se under)
SpeechBubble og SpeechBubble.Bubble endrer navn til Chat og Chat.Bubble. Codemod tar seg av renamingen.
topText
prop er nå delt opp iname
ogtimestamp
. Codemod vil legge topText inn iname
, men man må selv manuelt justere teksten hvis man har tatt i bruk en timestamp itopText
.illustration
prop heter nåavatar
(codemod fikser)illustrationBgColor
prop heter nåavatarBgColor
(codemod fikser)
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.
size="medium"
er nåsize="small"
(codemod fikser)size="small"
er nåsize="xsmall"
(codemod fikser)- Bruk uten size-prop blir satt til
size="medium"
av codemod
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:
- Importere Stepper fra "ds-react"
- Rename StepIndicator og StepIndicator.Step til Stepper og Stepper.Step
- Sette
orientation="horizontal"
(default er vertikal nå) - Sjekke at activeElement og onStepChange-indekseringen stemmer (step 1 returnerer nå 1 og ikke 0, som matcher den visuelle indekseringen)
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:
- Depender ikke lengre på
@material/ui
. - Depender ikke lengre på
react-popper
og@popperjs/core
- Byttet ut
classnames
medclsx
- Bruker nå
@floating-ui/react-dom-interactive
for popover/tooltip handling - Depender ikke lengre på
react-collapse
. Bruker egen animasjon for Accordion, ReadMore og ExpandableRow (Table). - ErrorMessage er nå
<p>
, var tidligere<div>
. - Label er nå
<label>
, var tidligere<p>
. - Checkbox og Radio sin
<label>
bruker nå<span>
instedenfor<div>
. Kan ende opp med valideringsfeil i dom hvis du rendrer noe annet enn tekst i label, så greit med en dobbelsjekk der. - Vi har også flyttet id-håndteringen til en lokal løsning i stedet for npm-pakken
uuid
. Komponenter i React 17 bruker nå en indeksert id, men React sinuseId
-hook for React 18 brukere.
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
- Mindre npm-pakker og versjoner: Prosjektet ditt vil gå fra ofte 20+ npm-pakker for nav-frontend til 2-5 nå. Alle de nye pakkene har også samme versjon, slik at du lettere kan holde alt oppdatert.
- Trenger ikke lengre Less-støtte: All ny styling er ren CSS og du kan skrive deg bort fra eks craco eller andre gamle less-plugins som ofte ikke lengre er aktivt støttet.
- Fremtidig støtte og nye oppdaterte komponenter.
- forwardRef: Alle komponenter bruker nå forwardRef, som gir deg mer kontroll om ønsket.
- Plug and play: Funker rett ut av boksen for de fleste rammeverk. Vite, Next, Gatsby, CRA, Parcel etc.
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">
.