-
Notifications
You must be signed in to change notification settings - Fork 6.8k
docs(theming): add initial guide for theming. #1246
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,127 @@ | ||
# Theming your Angular Material app | ||
|
||
|
||
### What is a theme? | ||
A **theme** is the set of colors that will be applied to the Angular Material components. The | ||
library's approach to theming is based on the guidance from the [Material Design spec][1]. | ||
|
||
In Angular Material, a theme is created by composing multiple palettes. In particular, | ||
a theme consists of: | ||
* A primary palette: colors most widely used across all screens and components. | ||
* An accent palette: colors used for the floating action button and interactive elements. | ||
* A warn palette: colors used to convey error state. | ||
* A foreground palette: colors for text and icons. | ||
* A background palette: colors used for element backgrounds. | ||
|
||
In Angular Material 2, all theme styles are generated _statically_ at build-time so that your | ||
app doesn't have to spend cycles generating theme styles on startup. | ||
|
||
[1]: https://material.google.com/style/color.html#color-color-palette | ||
|
||
### Using a pre-built theme | ||
Angular Material comes prepackaged with several pre-built theme css files. These theme files also | ||
include all of the styles for core (styles common to all components), so you only have to include a | ||
single css file for Angular Material in your app. | ||
|
||
You can include a theme file directly into your application from | ||
`@angular2-material/core/theming/prebuilt` | ||
|
||
If you're using Angular CLI, this is as simple as including one line | ||
in your `style.css` file: | ||
```css | ||
@import '~@angular2-material/core/theming/prebuilt/deeppurple-amber.css'; | ||
``` | ||
|
||
Alternatively, you can just reference the file directly. This would look something like | ||
```html | ||
<link href="node_modules/@angular2-material/core/theming/prebuilt/indigo-pink.css" rel="stylesheet"> | ||
``` | ||
The actual path will depend on your server setup. | ||
|
||
You can also concatenate the file with the rest of your application's css. | ||
|
||
### Defining a custom theme | ||
When you want more customization than a pre-built theme offers, you can create your own theme file. | ||
|
||
A theme file is a simple Sass file that defines your palettes and passes them to mixins that output | ||
the corresponding styles. A typical theme file will look something like this: | ||
```scss | ||
@import '~@angular2-material/core/theming/theming'; | ||
@import '~@angular2-material/core/theming/palette'; | ||
@import '~@angular2-material/core/core'; | ||
@import '~@angular2-material/button/button-theme'; | ||
// Plus imports for other components in your app. | ||
|
||
// Include the base styles for Angular Material core. We include this here so that you only | ||
// have to load a single css file for Angular Material in your app. | ||
@include md-core(); | ||
|
||
// Define the palettes for your theme using the Material Design palettes available in palette.scss | ||
// (imported above). For each palette, you can optionally specify a default, lighter, and darker | ||
// hue. | ||
$primary: md-palette($md-indigo); | ||
$accent: md-palette($md-pink, A200, A100, A400); | ||
$warn: md-palette($md-red); | ||
|
||
// Create the theme object (a Sass map containing all of the palettes). | ||
$theme: md-light-theme($primary, $accent, $warn); | ||
|
||
// Include theme styles for core and each component used in your app. | ||
@include md-core-theme($theme); | ||
@include md-button-theme($theme); | ||
// Plus includes for other components in your app. | ||
``` | ||
|
||
You only need this single Sass file; you do not need to use Sass to style the rest of your app. | ||
|
||
If you are using the Angular CLI, support for compiling Sass to css is built-in; you only have to | ||
add a new entry to the `"styles"` list in `angular-cli.json` pointing to the theme | ||
file (e.g., `unicorn-app-theme.scss`). | ||
|
||
If you're not using the Angular CLI, you can use any existing Sass tooling to build the file (such | ||
as gulp-sass or grunt-sass). The simplest approach is to use the `node-sass` CLI; you simply run: | ||
``` | ||
node-sass src/unicorn-app-theme.scss dist/unicorn-app-theme.css | ||
``` | ||
and then include the output file in your application. | ||
|
||
The theme file can be concatenated and minified with the rest of the application's css. | ||
|
||
#### Multiple themes | ||
You can extend the example above to define a second (or third or fourth) theme that is gated by | ||
some selector. For example, we could append the following to the example above to define a | ||
secondary dark theme: | ||
```scss | ||
.unicorn-dark-theme { | ||
$dark-primary: md-palette($md-blue-grey); | ||
$dark-accent: md-palette($md-amber, A200, A100, A400); | ||
$dark-warn: md-palette($md-deep-orange); | ||
|
||
$dark-theme: md-dark-theme($dark-primary, $dark-accent, $dark-warn); | ||
|
||
@include md-core-theme($dark-theme); | ||
@include md-button-theme($dark-theme); | ||
} | ||
``` | ||
|
||
With this, any element inside of a parent with the `unicorn-dark-theme` class will use this | ||
dark theme. | ||
|
||
### Styling your own components | ||
In order to style your own components with our tooling, the component's styles must be defined | ||
with Sass. | ||
|
||
You can consume the theming functions and variables from the `@angular2-material/core/theming`. | ||
You can use the `md-color` function to extract a specific color from a palette. For example: | ||
```scss | ||
.unicorn-carousel { | ||
background-color: md-color($primary); | ||
color: md-color($primary, default-contrast); | ||
} | ||
``` | ||
|
||
### Future work | ||
* When the "all" package is released, there will be a mixin that captures all of the component's | ||
theme styles so that you don't have to include them all individually. | ||
* Once CSS variables (custom properties) are available in all the browsers we support, | ||
we will explore how to take advantage of them to make theming even simpler. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it might be handy to have a list of the existing pre-built themes here as bullet points.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll add that once we have a full complement of prebuilts (only three right now)