govuk-frontend-docs/source/import-css/index.html.md.erb at 03ec25bd3d30614a025e0f6dcbb2820063bf8848 · alphagov/govuk-frontend-docs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
---
title: Import CSS
weight: 30
---

# Import CSS

To import the CSS from GOV.UK Frontend, you can either:

- add GOV.UK Frontend's CSS file to your HTML
- import the CSS into your own Sass file

## Add the CSS file to your HTML

If you decide to add the CSS to your HTML, you can do one of the following:

- set up your routing so requests for the CSS file are served from `node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css`
- copy the `node_modules/govuk-frontend/dist/govuk/govuk-frontend.min.css` file into your application

Then link the CSS file inside the `<head>` tag of your HTML page or page template.

```html
<head>
  <!-- // ... -->
  <link rel="stylesheet" href="<YOUR-STYLESHEETS-FOLDER>/govuk-frontend.min.css">
  <!-- // ... -->
</head>
```

## Import using Sass

To import all the Sass rules from GOV.UK Frontend, add the following to your Sass file:

```scss
@import "node_modules/govuk-frontend/dist/govuk";
```

## Import specific parts using Sass

If you want to improve how quickly your service's pages load in browsers, you can import only the Sass rules you need.

1. Import `node_modules/govuk-frontend/dist/govuk/base` in your Sass file.
2. Import only the Sass you need based on the components and other classes your service is using.

The biggest optimisations come from excluding any components or overrides you're not using.

You must import the layers in the order listed in the example below.

```scss
// 'Base' includes everything from settings, tools and helpers. Nothing
// in the base outputs any CSS.

@import "node_modules/govuk-frontend/dist/govuk/base";

// Basic content styles for typography, links etc. Approximately 10% of
// the CSS output if you include everything.

@import "node_modules/govuk-frontend/dist/govuk/core";

// Objects include things like the page template, grid and form groups.
// Approximately 5% of the CSS output if you include everything.

@import "node_modules/govuk-frontend/dist/govuk/objects";

// The components themselves - try to only include the components you
// are using in your project. Approximately 70% of the CSS output if
// you include everything.

<% components.each do |component| %>
@import "node_modules/govuk-frontend/dist/govuk/components/<%= component %>";
<% end %>

/*
// Alternatively, you can import all components:
@import "node_modules/govuk-frontend/dist/govuk/components";
*/

// Utilities, for example govuk-clearfix or govuk-visually-hidden.
// Approximately 1% of the CSS output if you include everything.

@import "node_modules/govuk-frontend/dist/govuk/utilities";

// Overrides, used to adjust things like the amount of spacing on an
// element. Override classes always include `-!-` in the class name.
// Approximately 15% of the CSS output if you include everything.

@import "node_modules/govuk-frontend/dist/govuk/overrides";

/*
// Alternatively, you can import the specific groups of overrides
// you need for your project:
<% examples = {
  'display' => %w(govuk-!-display-inline),
  'spacing' => %w(govuk-!-margin-4 govuk-!-static-padding-4),
  'text-align' => %w(govuk-!-text-align-left),
  'typography' => %w(govuk-!-font-size-19 govuk-!-font-weight-bold),
  'width' => %w(govuk-!-width-two-thirds)
} %>
<% overrides.each do |override| %>

// <%= override.sub('-', ' ').humanize %> overrides<% if examples.key?(override) %> - for example <%= examples[override].join(', ') %><% end %>
@import "node_modules/govuk-frontend/dist/govuk/overrides/<%= override %>";
<% end %>
*/
```

You can remove lines that import parts of the CSS you do not need.

[Read more about the different parts of GOV.UK Frontend’s CSS](https://github.com/alphagov/govuk-frontend/tree/main/packages/govuk-frontend/src).

## Import an individual component’s CSS using a single Sass import

You can also import a component and all its dependencies without importing `node_modules/govuk-frontend/dist/govuk/base` first.

For example, to import the button component, add the following to your Sass file:

```scss
@import "node_modules/govuk-frontend/dist/govuk/components/button";
```
We're deprecating using `_<COMPONENT_NAME>.scss` files (like `node_modules/govuk-frontend/dist/govuk/components/button/button`) and will remove them in the next major release of GOV.UK Frontend.

## Simplify Sass import paths

If you want to make Sass import paths shorter, add `node_modules/govuk-frontend/dist` to either your:

- [Sass load paths](https://sass-lang.com/documentation/at-rules/import#finding-the-file)
- [assets paths](http://guides.rubyonrails.org/asset_pipeline.html#search-paths) if you use Ruby in your project

You can then import without using `node_modules/govuk-frontend/dist/` in your import path. For example:

```scss
@import "govuk/components/button/button";
```

## Override with your own CSS

If you want to override GOV.UK Frontend's styles with your own styles, `@import` GOV.UK Frontend's styles before your own Sass rules.

## Silence deprecation warnings from dependencies in Dart Sass

If you're using Dart Sass 1.33.0 or greater, you may see deprecation warnings when compiling your Sass. For example:

```
DEPRECATION WARNING: Using / for division is deprecated and will be removed in Dart Sass 2.0.0.
```

You can silence the warnings caused by GOV.UK Frontend and other dependencies. If you're:

- calling the Sass compiler from the command line, [pass the `--quiet-deps` flag](https://sass-lang.com/documentation/cli/dart-sass#quiet-deps)
- using the JavaScript API, [include `quietDeps: true`](https://sass-lang.com/documentation/js-api#quietdeps) in the `options` object

You'll still see deprecation warnings if you're using `/` for division in your own Sass code.