Design system

Developers

Version update guide

Step-by-step guide to updating your code from DDD Design System v3 to v4 (Angular) and v5 to v6 (React)

The update introduces the following key improvements:

Type-ahead support for Angular components: Get coding faster with smart suggestions directly in your IDE.
New features and properties added across existing components: More flexibility, and improved accessibility.
New components available: Build more complex interfaces with less custom code.
Improved error checking during builds: Catch issues earlier for a smoother development experience.

This guide will help you update your project to DDD Design System v4 (Angular) and v6 (React).

The component is stable and supported in the latest major release. However, we recommend using the public form pattern for a more modular, flexible, and accessible approach.

Major differences between current and new version

One of the most significant changes in v4 (Angular) and v6 (React) is the renaming of component prefixes to align better across frameworks. In React, the prefix changes from GoA to Goab, while in Angular, it changes from goa- to goab-. See the following examples:

React

GoAButton will be GoabButton
GoAContainer will be GoabContainer

Angular

goa-button will be goab-button
goa-container will be goab-container

Migrating a React app

The React components for the DDD Design System are still located in the @abgov/react-components package.

1. Update dependencies

npm i @abgov/web-components@latest
npm i @abgov/react-components@latest

2. Rename all components name from GoAName to GoabName

After updating your packages, use your preferred code editor to perform a find/replace operation. Replace the prefix GoA-- with Goab-- for all component names. For example:

// Before
import {GoAAccordion, GoAButton, GoACallout, GoAHeadingSize } from '@abgov/react-components';

// After
import {GoabAccordion, GoabButton, GoabCallout, GoabAccordionHeadingSize} from '@abgov/react-components';

3. Update components' props that have changed

In v6, some of our properties have changed, go through the following table and make changes as necessary in your codebase.

Component	v5(LTS)	v6(latest)
Block	direction: Direction alignment: Alignment	direction: GoabBlockDirection alignment: GoabBlockAlignment
Checkbox	onChange: (name: string, value: boolean) => void;	onChange: (details: GoabCheckboxOnChangeDetail) => void;
Date picker	onChange: (name: string, value: Date) => void;	onChange: (details: GoabDatePickerOnChangeDetail) => void;
Dropdown	onChange: (name: string, value: string) => void;	onChange: (details: GoabDropdownOnChangeDetail) => void;
File uploader	onDelete: () => void; onCancel: () => void;	onDelete: (detail: GoABFileUploadOnDeleteDetail) => void; onCancel: (detail: GoABFileUploadOnCancelDetail) => void;
File uploader input	onSelect: (file: File) => void;	onSelect: (detail: GoabFileUploadInputOnSelectFileDetail) => void;
Form stepper	onChange: (step: number) => void;	onChange: (detail: GoabFormStepperOnChangeDetail) => void;
Input	onChange: (name: string, value: string) => void; onFocus: (name: string) => void; onBlur: (name: string, value: string) => void; onKeyPress: (name: string, value: string, key: string) => void;	onChange: (details: GoabInputOnChangeDetail) => void; onFocus: (details: GoabInputOnFocusDetail) => void; onBlur: (details: GoabInputOnBlurDetail) => void; onKeyPress: (details: GoabInputOnKeyPressDetail) => void;
Modal	width: string (deprecated) type: string (deprecated)	width: type:
Pagination	onChange: (page: number) => void;	onChange: (details: GoabPaginationOnChangeDetail) => void;
Popover	position: GoAPosition	position: GoabPopoverPosition
Radio group	onChange: (name: string, value: string) => void;	onChange: (details: GoabRadioGroupOnChangeDetail) => void;
Spacer	hSpacing: Spacing \| 'fill' vSpacing: Spacing	hSpacing: GoabSpacerHorizontalSpacing vSpacing: GoabSpacerVerticalSpacing
Table	onSort: (sortBy: string, sortDir: number) => void;	onSort: (details: GoabTableOnSortDetail) => void;
Tabs	onChange: (tab: number) => void;	onChange: (details: GoabTabsOnChangeDetail) => void;
Text area	countBy: CountBy onChange: (name: string, value: string) => void; onKeyPress: (name: string, value: string, key: string) => void;	countBy: GoabTextAreacountBy onChange: (details: GoabTextAreaOnChangeDetail) => void; onKeyPress: (details: GoabTextAreaOnKeyPressDetail) => void;
Calendar	onChange: (name: string, value: Date) => void;	onChange: (details: GoabCalendarOnChangeDetail) => void;
Spinner	type: SpinnerType size: SpinnerSize	type: GoabSpinnerType size: GoabSpinnerSize

Migrating an Angular app

@abgov/angular-components supports only Angular v16 and above.

1. Update dependencies

npm i @abgov/web-components@latest
npm i @abgov/angular-components@latest

2. Update angular component dependencies and import paths

// Before
import { Component, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";

@Component({
  selector: "app-accordion",
  standalone: true,
  templateUrl: "./accordion.component.html",
  schemas: [CUSTOM_ELEMENTS_SCHEMA] // Required for v3 but will be removed in v4
})
export class AccordionComponent {}

// After
import {GoabAccordion, GoabButton, GoabBadge} from '@abgov/angular-components';

@Component({
  selector: "app-accordion",
  standalone: true,
  imports: [GoabAccordion, GoabButton, GoabBadge],
  templateUrl: "./accordion.component.html"
})
export class AccordionComponent {}

3. Rename all components name from goa-name to goab-name in HTML templates

In v4, all Angular component names have been updated from goa- to goab-, with the following exceptions:

TwoColumnLayout: remains goa-two-column-layout
ThreeColumnLayout: remains goa-three-column-layout

As a result, imports and dependencies for pages using these components will not need to be changed.

Special Case:

The goa-one-column-layout component has been renamed to goab-column-layout

Next Steps:

After updating your packages and imports, perform a find/replace in your code editor to change goa- to goab- for all component names. For example:

<!--Before-->
<goa-circular-progress variant="inline" size="small" visible="true"></goa-circular-progress>
<goa-accordion heading="Heading" [open]="open"> Content 1</goa-accordion>
<goa-button (_click)="onClick()" type="tertiary">Tertiary</goa-button>
// After
<goab-circular-progress variant="inline" size="small" [visible]="true"></goab-circular-progress>
<goab-accordion heading="Heading" [open]="open"> Content 1 </goab-accordion>
<goab-button (onClick)="onClick()" type="tertiary">Tertiary</goab-button>

4. Update component margin properties

The margin properties for components have been standardized. Previously, margin values in Angular components were defined as string. Now, these margin properties are categorized under Spacing, ensuring consistency:

Property Name	v3	v4
`mt`	`string`	`Spacing`
`mb`	`string`	`Spacing`
`ml`	`string`	`Spacing`
`mr`	`string`	`Spacing`

5. Update component properties

In version 4, we have updated all Angular component properties from lowercase to camelCase. For example, a property previously named headingsize is now headingSize.

Additionally, in version 3, our Angular component properties were defined using basic types like string or boolean. In version 4, we introduced custom types for these properties and function arguments to ensure that the type checker validates the data structure specific to our components. You can find these changes detailed in the tables below:

Component	v3	v4
Accordion	headingsize: string headingcontent: slot	headingSize: GoabAccordionHeadingSize headingContent: TemplateRef
Badge	type: string	type: GoabBadgeType
Block	gap: string direction: string alignment: string	gap: Spacing direction: GoabBlockDirection alignment: GoabBlockAlignment
Button	type: string size: string variant: string leadingicon: string trailingicon: string _click: () => void	type: GoabButtonType size: GoabButtonSize variant: GoabButtonVariant leadingIcon: GoabIconType trailingIcon: GoabIconType onClick: () => void
Button group	alignment: string gap: string	alignment: GoabButtonGroupAlignment gap: GoabButtonGroupGap
Callout	type: string size: string	type: GoabCalloutType size: GoabCalloutSize
Checkbox	description: string \| slot _change: (e: CustomEvent) => void	description: string \| TemplateRef onChange: (e: GoabCheckboxOnChangeDetail) => void
Chip	leadingicon: string variant: string _onClick: () => void	leadingIcon: GoabIconType \| null variant: GoabChipVariant onClick: () => void
Container	type: string accent: string padding: string width: string title: slot actions: slot	type: GoabContainerType accent: GoabContainerAccent padding: GoabContainerPadding width: GoabContainerWidth title: TemplateRef actions: TemplateRef
Date picker	_change: (e: CustomEvent) => void	onChange: (detail: GoabDatePickerOnChangeDetail) => void
Dropdown	leadingicon: string _change: (name: string, value: string[] \| string \| null) => void	leadingIcon: GoabIconType onChange: (detail: GoabDropdownOnChangeDetail) => void
File uploader	_cancel: () => void _delete: () => void	onCancel: (detail: GoabFileUploadCardOnCancelDetail) => void onDelete: (detail: GoabFileUploadCardOnDeleteDetail) => void
File uploader input	variant: string _selectFile: (e: CustomEvent) => void	variant: GoabFileUploadInputVariant onSelectFile: (detail: GoabFileUploadInputOnSelectFileDetail) => void
App Footer Nav Section	Do not have	slot: 'nav' (Newly added)
App Footer Meta Section	Do not have	slot: 'meta' (Newly added)
Form item	labelsize: string requirement: string	labelSize: GoabFormItemLabelSize requirement: GoabFormItemRequirement
Form stepper	_change: (e: CustomEvent({detail: {step: number}}) => void	onChange: (detail: GoabFormStepperOnChangeDetail) => void
Form step	status: string	status: GoabFormStepStatus
Grid	gap: string	gap: Spacing
Hero banner	actions: slot	actions: TemplateRef
Icons	type: string size: string theme: string	type: GoabIconType size: GoabIconSize theme: GoabIconTheme
Icon button	type: string size: string theme: string _click: () => void	type: GoabIconType size: GoabIconSize theme: GoabIconTheme onClick: () => void
Input	type: string autocapidalize: string leadingicon: string trailingicon: string _trailingIconClick: () => void _change: (e: CustomEvent) => void _focus: (e: CustomEvent) => void _blur: (e: CustomEvent) => void _keyPress: (e: CustomEvent) => void	type: GoabInputType autocapitalize: GoabInputAutocapitalize leadingIcon: GoabIconType trailingIcon: GoabIconType onTrailingIconClick: () => void onChange: (detail: GoabInputOnChangeDetail) => void onFocus: (detail: GoabInputOnFocusDetail) => void onBlur: (detail: GoabInputOnBlurDetail) => void onKeyPress: (detail: GoabInputOnKeyPressDetail) => void
Microsite header	type: string feedbackurltarget: string headerurltarget: string	type: GoabMicrositeHeaderType feedbackUrlTarget: GoabLinkTarget headerUrlTarget: GoabLinkTarget
Modal	calloutvariant: string transition: string heading: string \| slot actions: slot _close: () => void	calloutVariant: GoabModalCalloutVariant transition: GoabModalTransition heading: string \| TemplateRef actions: TemplateRef onClose: () => void
Notification banner	type: string arialive: string dismiss: () => void	type: GoabNotificationType ariaLive: GoABAriaLiveType onDismiss: () => void
Pagination	variant: string _change: (e: CustomEvent) => void	variant: GoabPaginationVariant onChange: (detail: GoabPaginationOnChangeDetail) => void
Popover	position: string target: slot	position: GoabPopoverPosition target: TemplateRef
Progress indicator	variant: string size: string	variant: GoabCircularProgressVariant size: GoabCircularProgressSize
Radio item	description: string \| slot	description: string \| TemplateRef
Radio group	orientation: string _change: (e: CustomEvent) => void	orientation: GoabRadioGroupOrientation onChange: (e: GoabRadioGroupOnChangeDetail) => void
Side menu heading	meta: slot icon: string	meta: TemplateRef icon: GoabIconType
Skeleton loading	type: string size: string	type: GoabSkeletonType size: GoabSkeletonSize
Spacer	hSpacing: string vSpacing: string	hSpacing: GoabSpacerHorizontalSpacing vSpacing: GoaSpacerVerticalSpacing
Table	_sort: (e: CustomEvent) => void	onSort: (details: GoabTableOnSortDetail) => void
Table sort header	direction: string	direction: GoabTableSortDirection
Tab item	heading: string \| slot	heading: string \| TemplateRef
Tabs	type: string	type: GoabTabsType
Text area	countby: string _change: (e: CustomEvent) => void _keypress: (e: CustomEvent) => void	countBy: GoabTextAreaCountBy onChange: (detail: GoabTextAreaOnChangeDetail) => void onKeyPress: (detail: GoabTextAreaOnKeyPressDetail) => void
Tooltip	position: string halign: string	position: GoabTooltipPosition hAighn: GoabTooltipHorizontalAlignment
AppHeaderMenu	leadingicon: string	leadingIcon: GoabIconType
Calendar	_change: (e: CustomEvent) => void	onChange: (detail: GoabCalendarOnChangeDetail) => void
PageBlock	gap: string direction: string alignment: string	gap: Spacing direction: GoabBlockDirection alignment: GoabBlockAlignment
Spinner	type: string size: string	type: GoabSpinnerType size: GoabSpinnerSize

6. Update component slot content using Angular's ng-template

The most common manual update that teams will need to make involves adjusting slot content that uses slot="name" to reference a property. For example,

<!--Before-->
<goa-popover>
  <p>This is a popover</p>
  It can be used for a number of different contexts.
  <!--Slot target is required but can be forgotten because there are no errors alerted if we miss it-->
  <div slot="target">
    <goa-button type="secondary" size="compact">Click me</goa-button>
  </div>
</goa-popover>

<!--After-->
<!-- target property is required for goab-popover -->
<goab-popover target="popOverTarget">
  <p>This is a popover</p>
    It can be used for a number of different contexts.
  <ng-template #popOverTarget>
    <goab-button type="secondary" size="compact">Click me</goab-button>
  </ng-template>
</goab-popover>

Components with slot replaced by Angular ng-template references:

Component	v3	v4
Accordion	headingcontent: slot	headingContent: TemplateRef
Checkbox	description: string \| slot	description: string \| TemplateRef
Container	title: slot actions: slot	title: TemplateRef actions: TemplateRef
Hero banner	actions: slot	actions: TemplateRef
Modal	heading: string \| slot actions: slot	heading: string \| TemplateRef actions: TemplateRef
Popover	target: slot	target: TemplateRef
Radio item	description: string \| slot	description: string \| TemplateRef
Side menu heading	meta: slot	meta: TemplateRef
Tab item	heading: string \| slot	heading: string \| TemplateRef

7. Remove goaValue and goaChecked from the Angular input components

In v4, the goaValue and goaChecked directives can be removed from our input components when using Angular Forms. This applies to the following components:

Checkbox
Date picker
Dropdown
Input
Radio
Textarea

To handle user input in your app, you can use Angular's reactive forms, template-driven forms, or simply add an event handler. Below are examples of how to use our Angular checkbox component in these three different approaches:

1. Reactive

import { GoabCheckbox } from "@abgov/angular-components";
import { Component } from "@angular/core";
import { FormBuilder, FormGroup, ReactiveFormsModule } from "@angular/forms";
@Component({
  standalone: true,
  selector: "abgov-checkbox",
  templateUrl: "./checkbox.component.html",
  imports: [
    GoABCheckbox,
    ReactiveFormsModule
  ]
})
class CheckboxComponent {
  form!: FormGroup;
  constructor(private fb: FormBuilder) {
    this.form = this.fb.group({
      checked: [false]
    });
  }
}

<form [formGroup]="form">
  <goab-checkbox formControlName="checked" text="Item"></goab-checkbox>
</form>

2. Template-driven

import { GoabCheckbox } from "@abgov/angular-components";
import { Component } from "@angular/core";
import { FormsModule } from "@angular/forms";
@Component({
  standalone: true,
  selector: "abgov-checkbox",
  templateUrl: "./checkbox.component.html",
  imports: [
    GoabCheckbox,
    FormsModule,
  ]
})
class CheckboxComponent {
  checked = false;
}

<form>
  <goab-checkbox [(ngModel)]="checked" text="Item"></goab-checkbox>
</form>

3. Event handler

import { GoabCheckbox, GoabCheckboxOnChangeDetail } from "@abgov/angular-components";
import { Component } from "@angular/core";
@Component({
  standalone: true,
  selector: "abgov-checkbox",
  templateUrl: "./checkbox.component.html",
  imports: [
    GoABCheckbox
  ]
})
class CheckboxComponent {
  checked = false;
  onChange(event: GoabCheckboxOnChangeDetail) {
     this.checked = event.checked;
  }
}

<goab-checkbox name="item" text="Item" [value]="checked" (onChange)="onChange($event)"></goab-checkbox>

Join design system drop in hours to get feedback on your service, propose new components or patterns, suggest changes to existing resources, ask questions, and give feedback to the design system. These sessions are for Government of Alberta product teams.
Book time in drop in hours