How to use Icons in an Angular example project

[maxidorius]

After hours of fiddling around, I am not able to display a single icon in an Angular project.

I've read the following resources:

• https://clarity.design/get-started/developing/angular/
• https://angular.clarity.design/documentation/get-started
• https://clarity.design/foundation/icons/
• https://gist.github.com/mathisscott/81f86293259eb472f63830d1bf0320fb#file-setting-up-core-icons-txt

I've also came across some random pages, and after trying everything from scratch many times, it does not work.
Only a three-dot loading animation is shown instead of the icon itself.

Could it be possible to have a full step-by-step (including any commands) to get it to work with full file extract and filenames, using the latest versions of everything?
Knowing where to put things is the biggest hurdle here. Like I have no idea where to put the following snippet as no filename is given or precise instructions:

# Seen at https://clarity.design/foundation/icons/#import

import '@cds/core/icon/register.js';
import { ClarityIcons, userIcon } from '@cds/core/icon';

ClarityIcons.addIcons(userIcon);

Thanks!

[mathisscott]

I think the documentation assumes a certain degree of comfort/ease with angular that may not always be the case.

The reason the documentation does not tell people where to put that code is because the could be placed in a number of spots.

I prefer putting it in the app module. But others have had success by putting it in a component.ts file.

There is an example in our repo: https://github.com/vmware/clarity/blob/next/apps/core-angular-cli/src/app/app.module.ts

The example shows the icons being added in the constructor. I don't think that's necessary. But it's an example of how there are many ways to add icons.

[maxidorius]

Which version do you use to build it successfully? Maybe I can try with that one

[mathisscott]

Version of node? Well the terminal output says node 14. We typically use yarn (for now) on the Clarity team. That's yarn v1.

[hippee-lee]

Hi Max, I tested bootstrapping a new Angular app with the add schematic for @cds/angular. Maybe this will help. Here are the command line instructions I used to generate this app.. If you still run into problems, feel free to clone/fork that project.

CLI Commands

1. ng new test-cds-icons #(with no routing and scss)
2. cd test-cds-icons
3. ng add @cds/angular
4. npm install #not 100% sure why I needed to run this again, something for me to look into with the add schematic)
5. npm install normalize.css # Not sure why this isn't installed as a dep
6. npm start

Changes to app.module.ts

Then I modified the app.module.ts file with the following addditions:

...
import { cloudIcon, ClarityIcons } from '@cds/core/icon';
...
export class AppModule {
  constructor() {
    ClarityIcons.addIcons(cloudIcon);
  }
}

Changes made to app.component.html

<style>
    main {
      height: 100vh;
    }
</style>
<main cds-layout="vertical align:center">
  <h1>A Cloud Icon</h1>
  <cds-icon shape="cloud" size="xxl"></cds-icon>
</main>

I run node v14.16.0 on my local and it took me about 10 minutes from start to seeing the icon in my browser. Granted I am familiar with the project but it shouldn't take hours to scaffold out a new project. I'll look at the docs and see if anything should be updated or improved.

[maxidorius]

@hippee-lee Awesome, it works! So here are the differences between sucessfull steps and what the website steps are (or are not):

ng create

You selected SCSS but the Angular CLI has CSS as default. Nothing is said about this choice on the website. I guess that's one of the obvious choices if you are already familiar with the framework. Choosing CSS definitely doesn't work regardless of what is installed.

---

ng add

Website instructions

ng add @clr/angular

vs

ng add @cds/angular

-> @cds vs @clr

---

normalize.css

The website doesn't mention anything about npm install normalize.css, but it's also not needed to make it run. If @cds is installed, then normalize is required. If @clr is installed, it is not required/needed.

---

I managed to make it work with node v16 so no problem on that end. Am I loosing out on anything if I use @cds/angular instead of @clr/angular?

[hippee-lee]

Thanks for the feedback. A couple of notes. First, the choice for scss is personal, you should be able to chose whats is best for your project. Let us know if that is not the case. Second, re: @clr/angular vs @cds/angular here is what you need to know:

tl;dr

1. Use @clr/angular if you want the original Angular components (use this if you need things like datagrid or wizard or popovers (tooltips, signposts dropdowns etc) that are not yet available in the core components.
2. Use @cds/core if you are building for the future and can workaround the lack of things like datagrid or wizard or popovers (tooltips, signposts dropdowns) for now. Note, the core grid solution is in final polish and we should have the MVP out around the same time v6 is released later this fall. And, barring unforeseen circumstances, the general popover solution will be out before that with tooltips and friends to follow rather quickly.

@clr/angular

This is the original package of components that Clarity built. The components were built to work with Angular applications and the best documentation now lives here.

@cds/angular

These are angular wrappers for the @cds/core web components. The high level docs live here and the developer docs live here. These components are angular components that are generated from the web components based on the public API. They can be used just as you would the regular @cds/core web component but this package gives the app:

• type checking for the web components
• itellisense
• automatic icon registration

It also means the app doesn't need to use CUSTOM_ELEMENTS_SCHEMA to work with the core web-components.