> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Angular

> Install and configure the latest version of @metrifox/angular-sdk: standalone components, MetrifoxService, unified theme API, and the Angular playground.

Use the live playground to preview Customer Portal and Pricing Table before integrating the SDK into your application: **[Angular SDK Playground](https://playground.metrifox.com/angular)**.

***

## Installation

```bash theme={null}
npm install @metrifox/angular-sdk
# or
pnpm add @metrifox/angular-sdk
# or
yarn add @metrifox/angular-sdk
```

***

## Setup

### 1. Provide the SDK

Register providers (standalone apps typically use `app.config.ts`):

```typescript theme={null}
import { ApplicationConfig } from "@angular/core";
import { provideMetrifox } from "@metrifox/angular-sdk";

export const appConfig: ApplicationConfig = {
  providers: [provideMetrifox()],
};
```

### 2. Initialize once

Call `initialize` with your **client key** before using components (for example in `APP_INITIALIZER`, root component `ngOnInit`, or a dedicated setup service).

```typescript theme={null}
import { MetrifoxService } from "@metrifox/angular-sdk";

MetrifoxService.initialize({
  clientKey: "your-metrifox-client-key",
});
```

### 3. Global styles

Add SDK styles in `angular.json`:

```json theme={null}
{
  "styles": ["src/styles.css", "node_modules/@metrifox/angular-sdk/styles.css"]
}
```

Or in global CSS:

```css theme={null}
@import "@metrifox/angular-sdk/styles.css";
```

<Note>
  Targets **Angular 17, 18, and 19**. Components are **standalone** (no `NgModule` required).
</Note>

***

## Widgets

### `CustomerPortal`

```typescript theme={null}
import { Component } from "@angular/core";
import { CustomerPortalComponent, SectionConfig } from "@metrifox/angular-sdk";

@Component({
  selector: "app-billing",
  standalone: true,
  imports: [CustomerPortalComponent],
  template: `
    <metrifox-customer-portal
      [customerKey]="'your-customer-key'"
      [sectionsConfig]="sections"
      [theme]="portalTheme"
    />
  `,
})
export class BillingComponent {
  sections: SectionConfig[] = [
    { key: "subscription" },
    { key: "plan" },
    { key: "billingHistory", hidden: true },
  ];

  portalTheme = { general: { linkColor: "#2563eb" } };
}
```

Optional **`[theme]` input**: partial `CustomerPortalTheme`, merged with `MetrifoxService.initialize` theme for this component instance.

#### Section configuration

| Property    | Type                      | Description                   |
| ----------- | ------------------------- | ----------------------------- |
| `key`       | `SectionKey`              | Section identifier            |
| `hidden`    | `boolean`                 | Hide when `true`              |
| `component` | `Type<any>`               | Custom section component      |
| `props`     | `Record<string, unknown>` | Inputs / data for the section |

#### Built-in section keys

| Key                | Description                  |
| ------------------ | ---------------------------- |
| `upcomingInvoice`  | Next invoice details         |
| `subscription`     | Active subscription overview |
| `creditBalance`    | Wallet / credit balance      |
| `entitlementUsage` | Usage meters                 |
| `paymentOverview`  | Payment summary and methods  |
| `billingHistory`   | Past transactions            |
| `plan`             | Current plan                 |

#### Section anchors

| Anchor ID            | Section key        |
| -------------------- | ------------------ |
| `#upcoming-invoice`  | `upcomingInvoice`  |
| `#subscription`      | `subscription`     |
| `#credit-balance`    | `creditBalance`    |
| `#entitlement-usage` | `entitlementUsage` |
| `#payment-overview`  | `paymentOverview`  |
| `#billing-history`   | `billingHistory`   |
| `#plan`              | `plan`             |

***

### `PricingTable`

```typescript theme={null}
import { Component } from "@angular/core";
import { PricingTableComponent } from "@metrifox/angular-sdk";

@Component({
  selector: "app-pricing",
  standalone: true,
  imports: [PricingTableComponent],
  template: `
    <metrifox-pricing-table
      [checkoutUsername]="'your-checkout-username'"
      [productKey]="'your-product-key'"
      [theme]="pricingTheme"
    />
  `,
})
export class PricingComponent {
  pricingTheme = { plans: { planCards: { background: "#ffffff" } } };
}
```

#### Inputs

| Input                 | Type                | Required | Default | Description                             |
| --------------------- | ------------------- | -------- | ------- | --------------------------------------- |
| `checkoutUsername`    | `string`            | Yes      | —       | From **Settings → Checkout**            |
| `productKey`          | `string`            | Yes      | —       | Product identifier                      |
| `plansOnly`           | `boolean`           | No       | `false` | Only plans                              |
| `singlePurchasesOnly` | `boolean`           | No       | `false` | Only one-time purchases                 |
| `showTabHeader`       | `boolean`           | No       | `true`  | Plans vs purchases tabs                 |
| `theme`               | `PricingTableTheme` | No       | —       | Merged with global `theme.pricingTable` |

<Note>
  If both `plansOnly` and `singlePurchasesOnly` are `false` or omitted, both plans and single purchases render.
</Note>

***

## Styling

Global CSS import is required (see setup step 3). Without it, layout and components will not match the design system.

### Theme configuration (supported shape)

```typescript theme={null}
MetrifoxService.initialize({
  clientKey: "your-client-key",
  theme: {
    customerPortal?: CustomerPortalTheme;
    pricingTable?: PricingTableTheme;
  },
});
```

**Not supported on v2.0.0+:** `pricingTableTheme` at the root of the config object, or the legacy flat customer portal / pricing table theme shapes from releases before 2.0.0.

The Angular theme types mirror the React SDK: use the same grouping (`general`, `tabs`, `sections`, `buttons`, `lineItems`, `tables`, `modals`, `plans` for portal; `plans`, `tabs`, `checkoutBar` for pricing table). See the [React SDK styling reference](/sdks/frontend/react#styling) for field-level tables and copy/paste examples—the object shapes are intentionally aligned.

### Updating theme at runtime

`MetrifoxService.updateTheme` **replaces** the entire `theme` on the stored config. To adjust one area, merge with the previous value:

```typescript theme={null}
import { MetrifoxService } from "@metrifox/angular-sdk";

const next = {
  ...MetrifoxService.getTheme(),
  customerPortal: {
    ...MetrifoxService.getTheme()?.customerPortal,
    general: { linkColor: "#1d4ed8" },
  },
};
MetrifoxService.updateTheme(next);
```

***

## React ↔ Angular quick map

| React                   | Angular                        |
| ----------------------- | ------------------------------ |
| `metrifoxInit()`        | `MetrifoxService.initialize()` |
| `<CustomerPortal />`    | `<metrifox-customer-portal>`   |
| `<PricingTable />`      | `<metrifox-pricing-table>`     |
| `customerKey` prop      | `[customerKey]`                |
| `theme` prop            | `[theme]`                      |
| `onPlanSelect` callback | `(planSelected)` output        |

***

## Changelog and support

**[SDK changelog](/sdks/changelog)** — version history and breaking changes.\
npm: **`@metrifox/angular-sdk`**.\
Product docs: [docs.metrifox.com](https://docs.metrifox.com).