Introduksjon

Dette er en rask innføring i hvordan du tar i bruk kodepakkene våre. Hvis du er utvikler i Nav som skal starte på et nytt prosjekt, anbefaler vi at du også leser artikkelen om Golden Path for frontend i Nav.

Installering

yarn add @navikt/ds-react @navikt/ds-css
npm install @navikt/ds-react @navikt/ds-css

Bruk

import "@navikt/ds-css";
import { Button } from "@navikt/ds-react";

<Button variant="primary">Send inn søknad</Button>

All React-koden er tree-shakable, slik at du bare inkluderer den koden du trenger.

API

Alle komponentene er implementert med React forwardRef. Dette lar deg sende en ref som prop dersom du ønsker egen logikk på DOM-elementet.

const ref = useRef<HTMLDivElement>(null);

useEffect(() => {
  if (hasError && ref.current) ref.current.focus();
}, [hasError]);

return <ErrorSummary ref={ref}>(...)</ErrorSummary>;

De fleste komponenter utvider typen til det underliggende HTML-elementet de benytter. Flere komponenter bruker også OverridableComponent.

Styling

Komponentstyling er ikke integrert i React-koden. Du må selv importere @navikt/ds-css i prosjektet ditt manuelt. Stylingen er ikke auto-prefikset, så det er deres ansvar å løse dette ved hjelp av f.eks. PostCSS og Autoprefikser. De fleste bundlere løser dette for deg.

Pakken @navikt/ds-css inneholder all komponentstyling, fonter, ulike CSS-resets, print-styling, CSS-variablene våre fra @navikt/ds-tokens og normalize.css v8.

Stylelint

Vi anbefaler alle å ta i bruk stylelint-konfigurasjonen vår. Den sikrer at tokens og styling fra Aksel fungerer som forventet.

Fontlasting

Fonten vi benytter blir lastet fra CDN, slik at du må gjøre noen tilpasninger i løsningen din.

Vi angir font-display: swap, som medfører at en erstatningsfont vil bli lastet dersom den fonten ikke hentes raskt nok. For å unngå FOUT anbefales det å legge til en link-tag med preload i document-head. Du kan lese mer om dette i denne demoen.

<link
  rel="preload"
  href="https://cdn.nav.no/aksel/fonts/SourceSans3-normal.woff2"
  as="font"
  type="font/woff2"
  crossorigin
/>

Du må også oppdatere content security policy for å tillate font-src fra cdn.nav.no.

font-src 'self' https://cdn.nav.no

Ikoner

Ikonpakken vår inneholder totalt 800+ ikoner i stroke- og fill-versjon. Disse kan benyttes som separate React-komponenter eller direkte som SVG-er etter behov.

yarn add @navikt/aksel-icons
npm install @navikt/aksel-icons

import { StarIcon } from "@navikt/aksel-icons";

<StarIcon title="Alternativ tekst" />

Standard bredde og høyde på ikonene er satt til 1em for å gjøre det enkelt å plassere ikonene inline med tekst. Vi anbefaler hovedsakelig å bruke 24px der det er mulig, da ikonene er designet for denne størrelsen.

Vi anbefaler også å bruke title-attributtet der det er mulig, fremfor aria-label, ettersom dette gir en bedre opplevelse for skjermleserbrukere.

Språk

Dersom appen din har støtte for flere språk, kan du bruke Provider til å endre språket på komponentene.

Versjonering

Sørg for at alle Aksel-pakkene du bruker er på samme versjonsnummer. Dette sikrer at alle løsningene fra oss fungerer optimalt sammen.

Dependabot

Det er generelt anbefalt å bruke Dependabot for å holde avhengigheter oppdatert med tanke på sårbarheter. Dependabot bør da settes opp til å gruppere alle Aksel-pakkene slik at de oppgraderes samtidig. Dette kan gjøres ved å legge til følgende under - package-ecosystem: npm i filen .github/dependabot.yml:

groups:
      aksel:
        patterns:
          - '@navikt/aksel*'
          - '@navikt/ds*'

Se eventuelt hvordan andre har satt opp sin dependabot.yml-fil.