app-icon-preview-kit

Demo: https://pcordista.github.io/app-icon-preview-kit/

Installation

yarn add app-icon-preview-kit
# or
npm i app-icon-preview-kit

Peer dependencies: react >= 17, react-dom >= 17.

Quick start

import PreviewKit from 'app-icon-preview-kit';

export default function App() {
  return (
    <PreviewKit
      deviceSelected="BOTH"
      viewType="HOME"
      imageUrl="/my-icon.png"
      appName="MyApp"
      showUploadButton
      showCleanButton
    />
  );
}

You can also import the enums to avoid magic strings:

import PreviewKit, {
  PREVIEW_KIT_DEVICE_SELECTION,
  PREVIEW_KIT_VIEW_TYPE,
  PREVIEW_KIT_DEVICE_SIZE,
} from 'app-icon-preview-kit';

<PreviewKit
  deviceSelected={PREVIEW_KIT_DEVICE_SELECTION.BOTH}
  viewType={PREVIEW_KIT_VIEW_TYPE.HOME}
  deviceSize={PREVIEW_KIT_DEVICE_SIZE.MEDIUM}
/>

Props

deviceSelected (required)

Type: 'IOS' | 'ANDROID' | 'BOTH'

Which device(s) to render. 'BOTH' shows iOS and Android side by side (or stacked, depending on containerStyle.layout).

<PreviewKit deviceSelected="IOS" />

viewType

Type: 'HOME' | 'SPLASHSCREEN' | 'PREVIEW' — Default: 'HOME'

Which screen to render. Ignored when loading=true.

• 'HOME' — home screen with the custom icon highlighted.
• 'SPLASHSCREEN' — Expo-style splash (image centered on backgroundColor, device chrome overlaid).
• 'PREVIEW' — render arbitrary content inside the device frame (see preview).

<PreviewKit deviceSelected="BOTH" viewType="SPLASHSCREEN" />

preview

Type: ReactNode | string

Content rendered when viewType='PREVIEW'. A string is loaded inside an <iframe> (uses referrerPolicy="no-referrer"; sites with X-Frame-Options: DENY or restrictive frame-ancestors will refuse to load — use a React node in that case). A ReactNode is rendered inline, filling the screen.

<PreviewKit deviceSelected="IOS" viewType="PREVIEW" preview="https://my-app.dev" />
<PreviewKit deviceSelected="ANDROID" viewType="PREVIEW" preview={<MyAppShell />} />

allowPreviewNavigation

Type: boolean — Default: false

When true, the user can scroll and interact with the preview content. Otherwise the preview is rendered as a passive view (pointer events disabled).

imageUrl

Type: string | null — Default: null

URL or data URL of the icon. Used as the home icon, splash logo, and loading logo.

appName

Type: string — Default: 'Your app'

Label shown under the custom icon in home mode.

deviceSize

Type: 'SMALL' | 'MEDIUM' | 'LARGE' — Default: 'MEDIUM'

Visual size of the rendered device frame(s). MEDIUM is the canonical size; SMALL is ~75% and LARGE is ~130%.

<PreviewKit deviceSelected="BOTH" deviceSize="LARGE" />

showUploadButton

Type: boolean — Default: false

Display the upload button above the mockup.

showCleanButton

Type: boolean — Default: false

Display the button that clears the current image.

canChangeDevice

Type: boolean — Default: true

Allow the user to switch device via UI.

loading

Type: boolean — Default: false

Renders the loading screen (device chrome + native spinner + optional logo). Overrides viewType.

• iOS — classic activity indicator (8 radial bars with sequential fade).
• Android — Material circular progress (rotating bi-colored arc).

<PreviewKit deviceSelected="BOTH" loading imageUrl="/logo.png" backgroundColor="#0a0a0a" />

backgroundColor

Type: string — Default: '#ffffff'

Background color of splash/loading screens. Accepts any CSS color (hex, rgb, rgba, transparent).

containerStyle

Type: ContainerStyle

Outer container customization:

| Field | Type | Default | Description | |-------------------|-------------------------------|----------------|-------------| | backgroundColor | string | '#ffffff' | Outer container background color. Any CSS color. | | padding | number \| string | 16 | number → '16px'; also accepts CSS shorthand ('16px 24px'). | | layout | 'horizontal' \| 'vertical' | 'horizontal' | Device stacking direction when deviceSelected='BOTH'. | | fitDevices | boolean | false | Scale device frames to best fit the available container size (uses ResizeObserver). |

<PreviewKit
  deviceSelected="BOTH"
  containerStyle={{ backgroundColor: '#111', padding: 24, layout: 'vertical', fitDevices: true }}
/>

onImageChange

Type: (url: string | null) => void

Fired when the image is changed via upload or clear.

onDeviceChange

Type: (device: 'IOS' | 'ANDROID' | 'BOTH') => void

Fired when the user switches device via UI (requires canChangeDevice).

Scripts

| Command | Description | |------------------|-------------| | yarn dev | Run the playground at http://localhost:5173/ | | yarn build | Generate dist/ (ESM, CJS, index.d.ts). CSS is injected by the JS bundle at runtime. | | yarn typecheck | tsc --noEmit | | yarn preview | Preview the playground build |

License

MIT © Pedro Cordista