Overview

ds-plan is a simple self-contained Web Component for showing a Soracom plan tag. The component will sanitize the plan text, and display the correctly formatted official plan name and color.

Options

Simply include the plan name inside the ds-plan element, or use the plan="" attribute.

Plan lookup ignores case, whitespace, punctuation, and an optional leading plan. We recommend using either:

• The official plan name. i.e. plan-K2
• The short alias plan name. i.e. k2

<ds-plan>[plan name]</ds-plan>

<ds-plan plan="[plan name]"></ds-plan>

Inline usage

The ds-plan component can be used inline within text, automatically matching the surrounding font size.

Sizing

Bundle

You can include a bundle label by combining a plan key or alias with one of its registered bundle keys. For example, du and 50gb combine to form du50gb. Both of these forms resolve to plan-DU with its 50GB bundle label:

Alternatively, you can use the bundle attribute to specify a custom bundle label. This accepts free text and does not validate the bundle:

IMSI

Icons

Use icon to add an icon to the rendered plan tag. Use bundle-icon and imsi-icon to add icons to the bundle and IMSI labels.

Plan icon

Bundle icon

IMSI icon

Checkbox

Use type="checkbox" to render a checkbox input inside the plan tag, allowing users to select plans in a form.

Radio

Use type="radio" with a shared name attribute to create a radio group, allowing users to select a single plan.

Normalizing plan names

Use the standalone resolvePlan function to look up official plan names in server code, build tooling, or browser scripts. It uses the same lookup rules as ds-plan and works without a DOM or custom-element registration.

Server and build tooling

Import the resolver from the installed SDS package. This helper returns the full display name, including a matched bundle label, and preserves the original string when no match is found:

import { resolvePlan } from '@soracom/soracom-design-system/ds-plan/resolve';

export function getPlanName(value: string): string {
  return resolvePlan(value)?.name ?? value;
}

getPlanName('k2'); // 'plan-K2'
getPlanName('Plan K2'); // 'plan-K2'
getPlanName('du10gb'); // 'plan-DU (10GB)'
getPlanName('unknown'); // 'unknown'

resolvePlan accepts a string, null, or undefined. It returns an object containing key, plan, name, background-color, and text-color, along with any aliases, bundles, or beta metadata. Unknown or empty inputs return null.

Use name for the full display text. The plan field contains the base plan label, and bundle contains the matched bundle label when present. Without a bundle, name equals plan:

const resolved = resolvePlan('DU-50GB');

resolved?.key; // 'du'
resolved?.plan; // 'plan-DU'
resolved?.bundle; // '50GB'
resolved?.name; // 'plan-DU (50GB)'

The ds-plan component uses plan and bundle separately to render its labels. The bundle attribute overrides the matched bundle label; bundle="" hides it.

Browser scripts

Import the standalone module from the CDN inside a module script:

<script type="module">
  import { resolvePlan } from 'https://assets.soracom.io/sds/beta/ds-plan/resolve/index.mjs';

  const value = 'k2';
  const name = resolvePlan(value)?.name ?? value;

  console.log(name); // 'plan-K2'
</script>

Use the same SDS version for the resolver and the component. The ds-plan component already includes the resolver; import it separately when you need to resolve strings in your own code.

Supported plans

The table lists each plan and its bundles on separate rows. Bundle aliases combine each plan key or alias with the bundle key. For example, the du plan and 10gb bundle produce du10gb. These mappings control display labels; they do not validate bundle availability or eligibility.

Attributes

Manifest

The component manifest describes this component's API: its modifiers, structure, data attributes, CSS custom properties, accessibility notes, and example markup. It is consumed by tooling such as AI assistants and code generators.

Latest version: https://assets.soracom.io/sds/3.45.0/ds-plan/manifest.json?v=3.45.0

plans.json

Supported SORACOM short plan keys, base plan labels, color classes, optional alternate-name aliases, and optional bundles mapping normalized bundle keys to label text.

Source: https://assets.soracom.io/sds/3.45.0/ds-plan/plans.json