diff --git a/docs/theming-your-components.md b/docs/theming-your-components.md new file mode 100644 index 000000000000..6481e5e222fe --- /dev/null +++ b/docs/theming-your-components.md @@ -0,0 +1,69 @@ +#Theming your custom components +In order to style your own components with Angular Material's tooling, the component's styles must be defined with Sass. + +## Using `@mixin` to automatically apply a theme + +### Why using `@mixin` +The advantage of using a `@mixin` function is that when you change your theme, every file that uses it will be updated automatically. +Calling it with a different theme argument allow multiple themes within the app or component. + +### How to use `@mixin` +We can better theming our custom components adding a `@mixin` function to its theme file and then calling this function to apply a theme. + +All you need is to create a `@mixin` function in the custom-component-theme.scss + +```sass +// Import all the tools needed to customize the theme and extract parts of it +@import '~@angular/material/core/theming/all-theme'; + +// Define a mixin that accepts a theme and outputs the color styles for the component. +@mixin candy-carousel-theme($theme) { + // Extract whichever individual palettes you need from the theme. + $primary: map-get($theme, primary); + $accent: map-get($theme, accent); + + // Use md-color to extract individual colors from a palette as necessary. + .candy-carousel { + background-color: md-color($primary); + border-color: md-color($accent, A400); + } +} +``` +Now you just have have to call the `@mixin` function to apply the theme: + +```sass +// Import a pre-built theme +@import '~@angular/material/core/theming/prebuilt/deep-purple-amber'; +// Import your custom input theme file so you can call the custom-input-theme function +@import 'app/candy-carousel/candy-carousel-theme.scss'; + +// Using the $theme variable from the pre-built theme you can call the theming function +@include candy-carousel-theme($theme); +``` + +For more details about the theming functions, see the comments in the +[source](https://github.com/angular/material2/blob/master/src/lib/core/theming/_theming.scss). + +### Best practices using `@mixin` +When using `@mixin`, the theme file should only contain the definitions that are affected by the passed-in theme. + +All styles that are not affected by the theme should be placed in a `candy-carousel.scss` file. This file should contain everything that is not affected by the theme like sizes, transitions... + +Styles that are affected by the theme should be placed in a separated theming file as `_candy-carousel-theme.scss` and the file should have a `_` before the name. This file should contain the `@mixin` function responsible for applying the theme to the component. + + +## Using colors from a pallete +You can consume the theming functions from the `@angular/material/core/theming/theming` and Material pallete vars from `@angular/material/core/theming/palette`. You can use the `md-color` function to extract a specific color from a palette. For example: + +```scss +// Import theming functions +@import '~@angular/material/core/theming/theming'; +// Import your custom theme +@import 'src/unicorn-app-theme.scss'; + +// Use md-color to extract individual colors from a palette as necessary. +.candy-carousel { + background-color: md-color($candy-app-primary); + border-color: md-color($candy-app-accent, A400); +} +``` diff --git a/docs/theming.md b/docs/theming.md index 16a242516f52..cef94c7b891e 100644 --- a/docs/theming.md +++ b/docs/theming.md @@ -3,9 +3,9 @@ ### 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]. +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, +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. @@ -21,9 +21,9 @@ app doesn't have to spend cycles generating theme styles on startup. ### 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. +single css file for Angular Material in your app. -You can include a theme file directly into your application from +You can include a theme file directly into your application from `@angular/material/core/theming/prebuilt` If you're using Angular CLI, this is as simple as including one line @@ -35,8 +35,8 @@ in your `style.css` file: Alternatively, you can just reference the file directly. This would look something like ```html -``` -The actual path will depend on your server setup. +``` +The actual path will depend on your server setup. You can also concatenate the file with the rest of your application's css. @@ -56,25 +56,25 @@ the corresponding styles. A typical theme file will look something like this: // 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); +$candy-app-primary: md-palette($md-indigo); +$candy-app-accent: md-palette($md-pink, A200, A100, A400); // The warn palette is optional (defaults to red). -$warn: md-palette($md-red); +$candy-app-warn: md-palette($md-red); // Create the theme object (a Sass map containing all of the palettes). -$theme: md-light-theme($primary, $accent, $warn); +$candy-app-theme: md-light-theme($candy-app-primary, $candy-app-accent, $candy-app-warn); // Include theme styles for core and each component used in your app. // Alternatively, you can import and @include the theme mixins for each component // that you are using. -@include angular-material-theme($theme); +@include angular-material-theme($candy-app-theme); ``` 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 +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 @@ -87,8 +87,8 @@ 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 +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 { @@ -97,26 +97,16 @@ secondary dark theme: $dark-warn: md-palette($md-deep-orange); $dark-theme: md-dark-theme($dark-primary, $dark-accent, $dark-warn); - -@include angular-material-theme($dark-theme); + + @include angular-material-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 `@angular/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); -} -``` +### Theming your own components +For more details about theming your own components, see [theming-your-components.md](https://github.com/angular/material2/blob/master/docs/theming-your-components.md) ### Future work * Once CSS variables (custom properties) are available in all the browsers we support,