A lightweight TypeScript/JavaScript SDK for Short.io's URL shortening API, designed for browser environments with public key authentication. Zero runtime dependencies.
Use directly in the browser — no bundler needed:
<script type="module">
import { createClient } from 'https://cdn.jsdelivr.net/npm/@short.io/client-browser/dist/index.esm.js';
const client = createClient({ publicKey: 'your-public-api-key' });
const link = await client.createLink({
originalURL: 'https://example.com/very-long-url',
domain: 'your-domain.com'
});
console.log(link.shortURL);
</script>npm install @short.io/client-browserimport { createClient } from '@short.io/client-browser';
const client = createClient({
publicKey: 'your-public-api-key'
});
// Create a short link
const link = await client.createLink({
originalURL: 'https://example.com/very-long-url',
domain: 'your-domain.com'
});
console.log(link.shortURL); // https://your-domain.com/abc123
// Expand a short link
const expanded = await client.expandLink({
domain: 'your-domain.com',
path: 'abc123'
});
console.log(expanded.originalURL); // https://example.com/very-long-urlCreates a new Short.io client instance.
| Parameter | Type | Required | Description |
|---|---|---|---|
config.publicKey |
string |
Yes | Your Short.io public API key |
config.baseUrl |
string |
No | Custom API base URL (default: https://api.short.io) |
Creates a new short link.
| Parameter | Type | Required | Description |
|---|---|---|---|
domain |
string |
Yes | Your Short.io domain |
originalURL |
string |
Yes | The URL to shorten |
path |
string |
No | Custom path for the short link |
title |
string |
No | Link title |
tags |
string[] |
No | Tags for organization |
folderId |
string |
No | Folder ID |
cloaking |
boolean |
No | Enable link cloaking |
password |
string |
No | Password-protect the link |
passwordContact |
boolean |
No | Require contact info with password |
redirectType |
301 | 302 | 307 | 308 |
No | HTTP redirect status code |
utmSource |
string |
No | UTM source parameter |
utmMedium |
string |
No | UTM medium parameter |
utmCampaign |
string |
No | UTM campaign parameter |
utmContent |
string |
No | UTM content parameter |
utmTerm |
string |
No | UTM term parameter |
androidURL |
string |
No | Redirect URL for Android devices |
iphoneURL |
string |
No | Redirect URL for iPhones |
clicksLimit |
number |
No | Maximum number of clicks allowed |
skipQS |
boolean |
No | Skip query string forwarding |
archived |
boolean |
No | Create link as archived |
splitURL |
string |
No | A/B test destination URL |
splitPercent |
number |
No | A/B test traffic split percentage |
integrationAdroll |
string |
No | AdRoll integration pixel |
integrationFB |
string |
No | Facebook integration pixel |
integrationGA |
string |
No | Google Analytics integration |
integrationGTM |
string |
No | Google Tag Manager integration |
Returns Promise<CreateLinkResponse> with the full link object including shortURL, secureShortURL, id, and all configured properties.
Expands a short link to get its details.
| Parameter | Type | Required | Description |
|---|---|---|---|
domain |
string |
Yes | The Short.io domain |
path |
string |
Yes | The path of the short link |
Returns Promise<ExpandLinkResponse> (same shape as CreateLinkResponse).
Creates an encrypted short link using AES-GCM encryption. The original URL is encrypted client-side before being sent to the API; the decryption key is placed in the URL fragment (hash) and never sent to the server.
Takes the same parameters as createLink. Returns Promise<CreateLinkResponse> where shortURL includes the #key fragment for decryption.
const link = await client.createEncryptedLink({
originalURL: 'https://sensitive-content.example.com/private',
domain: 'your-domain.com'
});
// link.shortURL → https://your-domain.com/abc123#<base64-key>Conversion functions are standalone — no client instance needed. Import them directly:
import { trackConversion, getClickId, observeConversions } from '@short.io/client-browser';Or via CDN:
<script type="module">
import { observeConversions } from 'https://cdn.jsdelivr.net/npm/@short.io/client-browser/dist/index.esm.js';
observeConversions({ domain: 'your-domain.com' });
</script>Tracks a conversion event using navigator.sendBeacon(). Reads the clid (click ID) query parameter from the current page URL to attribute the conversion.
| Parameter | Type | Required | Description |
|---|---|---|---|
domain |
string |
Yes | Your Short.io domain |
conversionId |
string |
No | Custom conversion identifier |
value |
number |
No | Monetary or numeric value for the conversion |
Returns ConversionTrackingResult:
{
success: boolean; // true if clid was found and beacon sent
conversionId?: string;
clid?: string;
domain: string;
value?: number;
}const result = trackConversion({
domain: 'your-domain.com',
conversionId: 'purchase',
value: 49.99
});
if (result.success) {
console.log('Conversion tracked for click:', result.clid);
}Returns the clid query parameter from the current page URL, or null if not present.
const clickId = getClickId();Enables declarative conversion tracking via HTML data- attributes. Scans the DOM for elements with data-shortio-conversion and automatically binds event listeners. Also watches for dynamically added elements using a MutationObserver.
| Parameter | Type | Required | Description |
|---|---|---|---|
domain |
string |
Yes | Your Short.io domain |
Returns a ConversionObserver with a disconnect() method to remove all listeners and stop observing.
HTML attributes:
| Attribute | Description |
|---|---|
data-shortio-conversion |
Conversion identifier (empty string for no ID) |
data-shortio-conversion-value |
Numeric value for the conversion (ignored if not a valid number) |
Event binding by element type:
| Element | Event |
|---|---|
<form> |
submit |
<input> (non-submit) |
change |
<button>, <a>, <input type="submit"> |
click |
<!-- Declarative conversion tracking -->
<form data-shortio-conversion="signup">...</form>
<button data-shortio-conversion="purchase" data-shortio-conversion-value="29.99">Buy Now</button>
<a href="/pricing" data-shortio-conversion="cta-click">View Pricing</a>const observer = observeConversions({ domain: 'your-domain.com' });
// Later, to stop tracking:
observer.disconnect();| Format | File | Use case |
|---|---|---|
| ES Modules | dist/index.esm.js |
Modern bundlers (Vite, webpack, etc.) |
| CommonJS | dist/index.js |
Node.js / legacy bundlers |
| UMD | dist/index.umd.js |
Direct <script> tag usage |
Full type definitions are included. All types are exported:
import type {
ShortioConfig,
CreateLinkRequest,
CreateLinkResponse,
ExpandLinkRequest,
ExpandLinkResponse,
ConversionTrackingOptions,
ConversionTrackingResult,
ObserveConversionsOptions,
ConversionObserver,
ApiError
} from '@short.io/client-browser';API errors throw a standard Error with the message from the Short.io API response:
try {
const link = await client.createLink({
originalURL: 'https://example.com',
domain: 'your-domain.com'
});
} catch (error) {
console.error('Failed to create link:', error.message);
}- Visit your Short.io dashboard
- Go to Integrations & API
- Create a new public API key for your domain
Security: Public keys are safe to use in browser environments but have limited permissions. Never use private API keys in client-side code.
Requires browsers supporting:
- Fetch API
- Web Crypto API (for encrypted links)
- Beacon API (for conversion tracking)
- MutationObserver (for declarative conversion tracking)
MIT