@go-koala/ui

Angular component library for Koala products. Every control is standalone: import the symbols you need from @go-koala/ui into your standalone components or NgModule imports array. There is no aggregate NgModule in the package itself.

Quick start

1. Install the package and peer dependencies (match your Angular app majors).

2. Add global styles in angular.json → projects.<your-app>.architect.build.options.styles (order matters — theme first, then bundle):

   node_modules/@go-koala/ui/styles/koala-default-theme.css
   node_modules/@go-koala/ui/styles/koala-ui.bundle.css

3. Import and use (example: button):

   import { Button } from '@go-koala/ui';
   
   @Component({
     standalone: true,
     imports: [Button],
     template: `<koala-button label="Save" variant="primary" (click)="onSave($event)"></koala-button>`,
   })
   export class ExampleComponent {
     onSave(event: Event) {
       /* ... */
     }
   }

4. Optional — Tailwind in your app: If you do not use the prebuilt koala-ui.bundle.css, point Tailwind v4 at the package so utilities used in templates are generated:

   @source "../node_modules/@go-koala/ui/**/*.{js,mjs,html}";

Table of contents

• Quick start
• Install
• Peer dependencies
• Prerequisites
• How to use in your app
• Component reference
• Examples
• Troubleshooting
• Publishing (maintainers)

Install

npm i @go-koala/ui

Peer dependencies

Install versions that match your Angular app:

npm i @angular/core @angular/common @angular/cdk @angular/forms @angular/router \
  @ng-icons/core @ng-icons/lucide \
  class-variance-authority clsx tslib

Declared in the package peerDependencies — npm may warn if these are missing or mismatched.

Prerequisites

1. Styles bundle + theme

• koala-ui.bundle.css — Tailwind-based utilities used by library templates (built from this repo; includes Angular CDK overlay prebuilt styles where needed).
• koala-default-theme.css — CSS variables (design tokens) components expect.

2. Design tokens (CSS variables)

Components use semantic tokens such as:

--color-primary-bg, --color-primary-text, --color-secondary-bg, --color-brand-50, --color-content-1, --color-border-light, …

Default: import styles/koala-default-theme.css as in Quick start. Override :root in your app as needed. Token SCSS ships under tokens/ in the published package if you compile your own layers.

How to use in your app

Standalone components (recommended)

import { Button, Badge, Avatar } from '@go-koala/ui';

@Component({
  standalone: true,
  imports: [Button, Badge, Avatar],
  template: `
    <koala-badge label="New" variant="success" size="sm" radius="sm"></koala-badge>
    <koala-button label="Save" variant="primary"></koala-button>
  `,
})
export class ExampleComponent {}

Feature NgModule

Import the same standalone component classes into your module’s imports array (Angular 19+):

import { Button, Badge } from '@go-koala/ui';

@NgModule({
  imports: [Button, Badge],
  exports: [Button, Badge],
})
export class BookingUiModule {}

Tooltip (directive + content component)

import { TooltipDirective, TooltipContentComponent } from '@go-koala/ui';

@Component({
  standalone: true,
  imports: [TooltipDirective, TooltipContentComponent],
})
export class TooltipExampleComponent {}

Use [koalaTooltip] in templates (see Examples).

Component reference

All items below are exported from @go-koala/ui. Selector is the custom element / attribute to use in HTML.

| Export (TypeScript) | Selector | Kind | Notes | |---------------------|----------|------|--------| | ActionButton | koala-action-button | Component | Menu uses Angular CDK menu | | ActionInfoCardComponent | koala-action-info-card | Component | | | Avatar | koala-avatar | Component | | | Badge | koala-badge | Component | | | BottomNavComponent | koala-bottom-nav | Component | | | Button | koala-button | Component | Variants, loading, optional brnDialogTriggerFor → open() on modal ref | | ChargeListComponent | koala-charge-list | Component | Fee / charge rows | | ChatTopBarComponent | koala-chat-top-bar | Component | | | Checkbox | koala-checkbox | Component | | | ComboBox | koala-combo-box | Component | | | ContactCardComponent | koala-contact-card | Component | | | ContactCardDetailComponent | koala-contact-card-detail | Component | | | ConversationTimestampComponent | koala-conversation-timestamp | Component | | | DateRangeComponent | koala-date-range | Component | Native calendar grid + range/single | | DetailSlotComponent | koala-detail-slot | Component | | | DividerComponent | koala-divider | Component | | | ErrorScreenComponent | koala-error-screen | Component | | | GuestDetailsComponent | koala-guest-details | Component | | | InfoTextComponent | koala-info-text | Component | | | InputComponent | koala-input | Component | | | MessageComponent | koala-message | Component | | | MessageActionComponent | koala-message-action | Component | | | MessageTopBarComponent | koala-message-top-bar | Component | | | ModalComponent | koala-modal | Component | exportAs: 'koalaModal' — use #ref="koalaModal" and ref.open() / ref.close() | | PaneHeadingsComponent | koala-pane-headings | Component | | | PaymentProtectionComponent | koala-payment-protection | Component | | | PaymentSummaryCardComponent | koala-payment-summary-card | Component | | | PricingCardComponent | koala-pricing-card | Component | | | RadioButton | koala-radio-button | Component | | | SearchableSelectComponent | koala-searchable-select | Component | | | SegmentControlComponent | koala-segment-control | Component | | | Select | koala-select | Component | Native <select> styling | | SheetComponent | koala-sheet | Component | Side / top / bottom panel | | StepsTimelineComponent | koala-steps-timeline | Component | | | SystemActionsComponent | koala-system-actions | Component | | | TextAreaComponent | koala-text-area | Component | | | ToastComponent | koala-toast | Component | | | TooltipDirective | [koalaTooltip] | Directive | Angular CDK overlay | | TooltipContentComponent | koala-tooltip-content | Component | Used with tooltip directive |

Types: TooltipPosition, TooltipSide (tooltip configuration).

Examples

Badge

<koala-badge label="Primary" variant="primary" size="sm" radius="sm"></koala-badge>
<koala-badge label="Success" variant="success" size="sm" radius="sm"></koala-badge>

Button (click)

Button supports the usual DOM click on <koala-button>.

<koala-button
  label="Save"
  variant="primary"
  size="md"
  borderRadius="half"
  (click)="save($event)"
></koala-button>

Variants include: primary, primary-outline, secondary, tertiary, green-gradient, black-gradient, danger, danger-outline, ghost.

Button opening a modal

Pass a template ref to anything that exposes open() (for example ModalComponent with #dlg="koalaModal"). Input names stay brnDialogTriggerFor / brnDialogTrigger for backward compatibility:

<koala-button label="Open" variant="secondary" [brnDialogTriggerFor]="dlg"></koala-button>

<koala-modal #dlg="koalaModal" title="Example" [showFooter]="true">
  <p>Content</p>
</koala-modal>

Avatar

<koala-avatar size="md" firstName="Ada" lastName="Lovelace"></koala-avatar>

Divider

<koala-divider
  label="Section"
  labelPosition="center"
  variant="default"
  thickness="normal"
  gap="md"
  [fullWidth]="true"
></koala-divider>

Checkbox

<koala-checkbox [ngModel]="accepted" label="I agree"></koala-checkbox>

(Use FormsModule or reactive forms as usual.)

Tooltip

<button type="button" koalaTooltip tooltipText="Help text">Hover me</button>

Troubleshooting

| Symptom | Likely cause | What to do | |--------|----------------|------------| | Controls invisible / unstyled | Missing bundle or Tailwind scan | Add koala-ui.bundle.css or @source for @go-koala/ui (Quick start) | | Wrong colors / invisible text | Missing CSS variables | Import koala-default-theme.css (Prerequisites) | | koala-charge-list vs ChargeListComponent | Export name ≠ selector | Use koala-charge-list in HTML | | Overlay / menu issues | Missing CDK styles | Ensure koala-ui.bundle.css (includes CDK overlay) is in styles |

Publishing (maintainers)

Full checklist: docs/RUNBOOK-koala-ui.md (from repo root koala-design-system/docs/).

Short version:

1. Regenerate CSS from repo root when needed: npm run build:koala-default-theme (token/theme changes) and/or npm run build:koala-ui-css (templates / Tailwind entry changes). Commit updated files under styles/.
2. Bump version in projects/koala-components/package.json.
3. npx ng build koala-components
4. cd dist/koala-components && npm publish --access public

Ensure the tarball includes the full ng-packagr output (FESM bundles, typings, README.md, styles/, tokens/).

More help

• Angular
• Angular CDK
• Koala monorepo / internal docs for token sources and app wiring.