The UK Intelligence Community Angular UI Kit

The Intelligence Community Design System helps the United Kingdom's Intelligence Community (MI6, GCHQ, MI5, and partners) to quickly build powerful capabilities that are accessible and easy to use.

This is a joint project led by MI6, working with GCHQ, MI5 and HMGCC (our national security partner).

[!WARNING] This Angular-native package is not maintained or supported by the core ICDS team and is entirely community-developed

Choice of approach

Angular can support the use of non-native custom components for building apps as well as the standard importing of native Angular-based component libraries. The ICDS component suite has been configured to provide wrapped versions of each component that can be used as if they were native components for ease, but as the core components are written as standards-compliant web components, developers are free to use the original suite in their Angular apps instead.

The native component wrappers have been created as this will allow Angular developers a better way to interface with the UI Kit however and so this is the recommended approach. A list of the benefits of using the native components can be found on Stencil's docs, but to summarise here: Trying to use non-Angular components creates some minor friction or pain points that an app developer will need to deal with; by using these wrapped components that's no longer a concern.

If you would prefer to use the vanilla web components instead you can do so by following the Getting Started guide for vanilla components here and also including CUSTOM_ELEMENTS_SCHEMA in the schemas key of either the Module or the Component declaration of any components that use the ICDS components.

Versioning and Deprecations

Version Compatibility

This package will be kept up to date with the latest version of the ICDS web-components and we shall aim to ensure that it is tested against modern versions of Angular going forward (v20+). If this becomes impractical or there is a breaking change that creates version-specific dependencies, then this section of the README will be updated with the relevant versioning.

Deprecation Policy

As requested by the ICDS team, if this package does not receive any updates within 12 months then it shall be considered deprecated.

Installing

Last tested with Angular 20.3.0 & 21.0.0

To install the components you have two different methods. Either using the ng add command to streamline the process or a manual install:

Using ng add

This will install all the necessary packages and setup your project. In the root of your project:

ng add @ukic/angular-community-supported

Manual setup

Step one

# using npm
npm install @ukic/angular-community-supported @ukic/fonts

# using yarn
rm package-lock.json
yarn add @ukic/angular-community-supported @ukic/fonts

Step two

To get the correct styling with the ICDS components, you will need to import the core CSS file and the fonts CSS file.

Add the following into your angular.json file in the build styles config

{
    "styles": [
        ...
        "node_modules/@ukic/fonts/dist/fonts.css",
        "node_modules/@ukic/angular-community-supported/css/core.css"
    ]
}

In order to be rendered consistently across browsers and in line with modern standards, each of the ICDS components uses styles from a global CSS file based on Normalize.css.

If you would like to import these styles to apply them to the rest of your project and slotted elements used within any of the ICDS components, add the following into the top level CSS file as well.

{
    "styles": [
        ...
        "node_modules/@ukic/angular-community-supported/css/normalize.css"
    ]
}

Step three

Due to a conflicting issue with TypeScript you need to add skipLibCheck: true to your tsconfig.json.

Using the components in your app

To use the ICDS components in Angular your usage will vary based on if you are using a standalone project or using NgModules.

NOTE: There is currently no Angular-specific per-component documentation (this page is it) though using the web components reference in combination with intellisense should work well.

NgModule application

You will need to import the ICDSModule from @ukic/angular-community-supported into your NgModule. This will import all of the components and make them available and then you can follow the web component documentation.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import { ICDSModule } from '@ukic/angular-community-supported';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    ICDSModule,
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

Standalone application

You will need to import each component as you need it into your components from @ukic/angular-community-supported/standalone. If you are using a form control you will need to also import ICDSValueAccessorModule into your component. Once you've imported it you can then you can follow the web component documentation.

import { Component } from '@angular/core';
import { IcButton } from '@ukic/angular-community-supported/standalone';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [IcButton],
  template: `<ic-button variant="primary">I am a button</ic-button>`
})
export class AppComponent {}

import { Component, OnInit } from '@angular/core';
import { FormControl, FormsModule, ReactiveFormsModule } from '@angular/forms';
import { IcTextField, ICDSValueAccessorModule } from '@ukic/angular-community-supported/standalone';

@Component({
  selector: 'app-root',
  template: `<ic-text-field label="Text field control" placeholder="Text field..." [formControl]="textFieldControl"></ic-text-field>`,
  standalone: true,
  imports: [
    FormsModule,
    ReactiveFormsModule,
    IcTextField,
    ICDSValueAccessorModule
  ]
})
export class FormControlsComponent {
  textFieldControl = new FormControl('i am a text field');
}

Testing locally

To test the current Angular output of your local repo there are numerous approaches. The following guide will likely be the simplest approach. This is useful for testing that changes made to the web components are accurately reflected in the Angular wrappers and also to ensure the "add" schematic is functioning properly.

1 - Prep the source

From the root of ic-ui-kit

• Build the components: npm run build
• Pack them: ./pack-all-tars.sh

Whenever changes are made to the components or Angular output config this step will need to be run again. They can be prepped more efficiently by sitting in the web-components or Angular package folders and running the npm [build|pack] commands.

2 - Create the test app

ng new add-test
cd add-test

3 - Point npm at the local artefacts

In the package.json of the new app add the following to the "dependencies" manually (changing the version numbers appropriately):

"@ukic/angular": "<path to ic-ui-kit root>/packages/angular/ukic-angular-#.#.#.tgz",
"@ukic/web-components": "<path to ic-ui-kit root>/packages/web-components/ukic-web-components-#.#.#.tgz"

Run npm install

4 - Run the schematic

ng add @ukic/angular-community-supported

You'll now be able to add ICDS components to a vanilla Angular app setup as above.

NOTE: Once changes have been made and packaged as per step 1, the test app will need to have the @ukic packages updated/re-installed to pick up the latest changes.

Previewing changes

Potentially when trying to serve the new app and load it in a browser for preview Vite will block access and return an error along the lines of "<hostname> is not a permitted origin". This will certainly be common in cloud IDE environments such as Codespaces, GitPod or Cloud9 etc.

This can be resolved by adding the following to the projects.architect.serve block of the app's angular.json:

"options": {
  "allowedHosts": ["<hostname>"],
},

Alternate: npm link

Potentially using npm's link command to create a symlink between the test app and the local dist folder could be a neater solution and would be more responsive to changes once built. That approach however seems more prone to issues from multiple different causes and so a specific guide will not be provided.

Contributing

We have a couple of resources to help you with contributing.

• To find out more about the different types of contributions, the criteria, raising issues or our release roadmap, read how to contribute to the Design System and UI Kit.
• Make sure to also read our coding standards and technical instructions.
• IC Design System guidance site repository contains the code and content for the Design System guidance site.
• IC UI Kit repository contains the code and content for the web components.

Changelog

For a comprehensive changelog of the Angular components, please read the web components CHANGELOG. The released updates made to the web components are reflected on the Angular components.

Security

If you've found a vulnerability, we want to know so that we can fix it. Our security policy tells you how to do this.

Questions about the departments

The team is only able to talk about the projects we've put on GitHub 🕵️. We unfortunately can't talk about the work of our departments 😢.

Visit our websites to learn more about:

• The Secret Intelligence Service (MI6).
• The Government Communications Headquarters (GCHQ).
• The Security Service (MI5).
• His Majesty's Government Communications Centre (HMGCC).

License

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. The documentation is and available under the terms of the Open Government License v3.0.

© Crown copyright 2026