nsh

nsh is the core module: the reactive API (signals, computed values, effects, context), mount, token, the host elements View, Text, Scroll and Overlay, selectable views, the safe area and the keyboard, animation, the device and its environment, PanResponder, the clipboard, the photo picker, storage, the host channel, keyboard shortcuts, native components and modules, accessibility, and the TypeScript types of elements, styles and events. The reactive graph itself runs natively in Rust; reading a signal is a call into the runtime that costs a few nanoseconds, and only your own closures run in the JavaScript interpreter.

import { batch, cleanup, computed, context, effect, ErrorBoundary, mount, Overlay, Scroll, signal, split, Text, token, untracked, View } from "nsh";
import { Input } from "nsh/base";

NSH’s reactivity follows the same model as SolidJS: a component function runs once, and the parts of the UI that read signals are updated in place when those signals change. There is no re-render of the component and no virtual DOM. See Reactivity for the guide.

#signal

function signal<T>(value: T, options?: SignalOptions<T>): Signal<T>;
function signal<T = undefined>(): Signal<T | undefined>;

interface Signal<T> {
  (): T;                              // read (tracked)
  set(value: T): void;                // write
  update(fn: (value: T) => T): void;  // write from the current value
}

interface SignalOptions<T> {
  /** When a new value counts as a change (default `===`); `false`: always. */
  equals?: false | ((previous: T, next: T) => boolean);
}

A signal holds a value. Calling it reads the value and, inside a tracking scope (JSX expressions, computed, effect), subscribes that scope to it. set and update write it; everything that read it updates.

import { mount, signal, Text, View } from "nsh";

function Counter() {
  const count = signal(0);
  return (
    <View style={{ padding: 24, gap: 12 }}>
      <Text>Count: {count()}</Text>
      <Text onPress={() => count.update((n) => n + 1)}>Add one</Text>
    </View>
  );
}

mount(Counter);

By default a write that is === to the current value does nothing. Pass equals: false to notify on every write (useful when you mutate an object in place and set the same object again), or your own comparison:

const items = signal<string[]>([], { equals: false });
const point = signal({ x: 0, y: 0 }, { equals: (a, b) => a.x === b.x && a.y === b.y });

#computed

function computed<T>(fn: (previous: T | undefined) => T, options?: SignalOptions<T>): Accessor<T>;

interface Accessor<T> {
  (): T;
}

A value derived from signals. fn runs again when a signal it read changes; readers of the computed value only update when its result changes (by equals, === by default). fn receives the previous result.

const first = signal("Ada");
const last = signal("Lovelace");
const full = computed(() => `${first()} ${last()}`);
full(); // "Ada Lovelace"

Use computed when a derivation is expensive or read in several places. For a cheap expression, a plain function (const full = () => first() + " " + last()) is just as reactive.

#effect

function effect(fn: () => void): void;

Runs fn after rendering, and again whenever a signal it read changes. Use effects for side effects: logging, timers, talking to native modules. An effect belongs to the component (or effect) it was created in and is disposed with it.

const query = signal("");
effect(() => {
  console.log("query is now", query());
});

To undo something before the effect runs again (or when its component goes away), call cleanup inside it.

#batch

function batch<T>(fn: () => T): T;

Runs fn and applies all its writes together at the end, so readers update once instead of once per write. Returns what fn returns.

batch(() => {
  first.set("Grace");
  last.set("Hopper");
}); // `full` recomputes once

#untracked

function untracked<T>(fn: () => T): T;

Runs fn without subscribing the current scope to what it reads. Use it to read a signal inside an effect or JSX expression without depending on it.

effect(() => {
  // Runs again when `query` changes, not when `page` changes.
  search(query(), untracked(() => page()));
});

#cleanup

function cleanup(fn: () => void): void;

Registers fn to run before the current effect runs again, or when the current component or effect goes away.

function Clock() {
  const now = signal(new Date());
  const timer = setInterval(() => now.set(new Date()), 1000);
  cleanup(() => clearInterval(timer));
  return <Text>{now().toLocaleTimeString()}</Text>;
}

#context

function context<T>(defaultValue: T): Context<T>;

interface Context<T> extends Accessor<T> {
  Provider: (props: { value: T; children?: JSX.Element }) => JSX.Element;
}

A value a component provides to everything it renders, however deep. Calling the context (Theme()) reads the nearest provider’s value, or defaultValue without one.

import { context, mount, signal, Text, View } from "nsh";

const Theme = context<"light" | "dark">("light");

function Label(props: { text: string }) {
  return <Text style={{ color: Theme() === "dark" ? "#fff" : "#000" }}>{props.text}</Text>;
}

function App() {
  const dark = signal(false);
  return (
    <Theme.Provider value={dark() ? "dark" : "light"}>
      <View style={{ flex: 1, padding: 24, backgroundColor: dark() ? "#000" : "#fff" }}>
        <Label text="Hello" />
        <Text onPress={() => dark.update((d) => !d)}>Toggle</Text>
      </View>
    </Theme.Provider>
  );
}

mount(App);

#mount

function mount<P extends object>(app: Component<P>, props?: P): () => void;

Renders app into the surface (the window, or the NshAppView / NshView the app is embedded in) and returns a function that removes it. Every app’s entry file ends with mount(App).

mount(App);

#split

function split<T extends object, K extends readonly (keyof T)[]>(
  props: T,
  keys: K,
): [Pick<T, K[number]>, Omit<T, K[number]>];

Splits a props object into the props named in keys and the rest. Both halves stay reactive: props whose values change are getters, and split keeps them as getters. Use it in a component that handles some props itself and passes the others on. Destructuring props (const { label } = props) would read them once and lose updates.

import { split, Text, View } from "nsh";
import { Input, type InputProps } from "nsh/base";

function LabeledInput(props: InputProps & { label: string }) {
  const [own, rest] = split(props, ["label"]);
  return (
    <View style={{ gap: 4 }}>
      <Text>{own.label}</Text>
      <Input {...rest} />
    </View>
  );
}

#ErrorBoundary

function ErrorBoundary(props: {
  fallback: JSX.Element | ((error: unknown, reset: () => void) => JSX.Element);
  children?: JSX.Element;
}): JSX.Element;

Renders its children, or fallback once something under them throws: a component’s body, a binding, an effect or an event handler. The part that failed is removed and the fallback shows in its place. fallback(error, reset) gets the thrown value and reset, which renders the children again; a fallback that takes no arguments is shown as it is. A failure goes to the nearest boundary above it, and one in a fallback to the boundary above that. Rust components use catch_error (Error boundaries).

import { ErrorBoundary, Text, View } from "nsh";

function Feed() {
  return (
    <ErrorBoundary
      fallback={(error, reset) => (
        <View>
          <Text>{error instanceof Error ? error.message : String(error)}</Text>
          <Text onPress={reset}>Try again</Text>
        </View>
      )}
    >
      <Posts />
    </ErrorBoundary>
  );
}

#token

function token<K extends keyof Tokens>(name: K): Tokens[K];

The design token name of the app’s theme ("theme" in nsh.json, over shadcn/ui’s tokens) in the appearance shown: a color as #rrggbbaa, a length as a number of points, a font as its family name. Names are the theme’s CSS variables without -- (primary, muted-foreground, radius, font-mono, and the app’s own, such as up). Reading it is reactive: a component, memo or effect that reads a token runs again when the theme or the appearance changes. Tokens lists the app’s tokens with their types; NSH writes it into .nsh/types/nsh/tokens.d.ts from the theme. For classes, name the tokens directly (bg-primary, rounded-(--radius)): Theme tokens.

import { effect, token } from "nsh";

effect(() => console.log("primary is", token("primary"), "radius", token("radius")));

#View, Text, Scroll, Overlay

function View(props: ViewProps): YNode;
function Text(props: TextProps): YNode;
function Scroll(props: ScrollProps): YNode;
function Overlay(props: OverlayProps): YNode;

The host elements nsh exports, written as tags: <View>, <Text>, <Scroll>, <Overlay> (its children on top of the window, placed against an anchor: Overlay). The compiler makes the native view in place for a tag that names one of them through its import (an alias too), so importing them costs nothing at run time. They are components like any other, so they can also be passed around (const Tag = inline ? Text : View). nsh exports the other primitives the same way: List, Image, Canvas, WebView and Video, each with its own reference page. Their props are documented under Elements. The text input, Input, comes from nsh/base.

#Safe area and keyboard

CSS’s environment variables keep content clear of system UI, in any view’s padding and margin (padding, paddingTop, …, the same margin keys; Tailwind’s p* / m* arbitrary values; the Styled methods .p_safe_area(), .pt_safe_area_plus(..), .pb_keyboard(), … in Rust). Their values are EnvValues: env(name), env(name, <length>), calc(env(name) + <length>) and calc(<length> + env(name)).

<View style={{ flex: 1, paddingTop: "env(safe-area-inset-top)", paddingBottom: "env(keyboard-inset-height)" }}>…</View>

#safeArea and safeAreaInsets

safeArea() is the surface’s safe area (safe_area() in Rust); safeAreaInsets() the insets where a component renders (cx.insets() in Rust), the values of the safe-area-inset-* variables. Both are reactive Edges ({ top, right, bottom, left } in points). See safeArea and safeAreaInsets.

#Keyboard and keyboardFrame

Keyboard.dismiss() hides the software keyboard (dismiss_keyboard() in Rust) and keyboardFrame() tells you how much of the screen it covers (keyboard_height() and keyboard_duration() in Rust). See Hiding the keyboard and The keyboard’s height.

#Selectable views

<View selectable> (view().selectable(true) in Rust) makes the texts inside it select together, as a web page’s do: one selection runs across views, Text elements and TextViews, in reading order. See Text selection.

#Animation

The animation API animates on the UI thread. You create an animated value, bind it (or values derived from it) to a style property, and start an animation; from then on every frame is computed natively, without running the app’s code. A busy engine or JS thread cannot make the animation stutter, and an animation costs the app no work per frame. Rust code uses animated_value(), motion(), Animation, Spring, Timing, KeyframeTiming, MotionPreset and Easing from nsh_core::prelude and binds values with the .bind_* methods of elements; TSX imports them from nsh.

use nsh_core::{element::LayoutAnimation, prelude::*}; // animated_value, motion, Animation, Spring, Timing, Keyframe, KeyframeTiming, MotionPreset, MotionSpec, Easing, animate_layout

import { Animated, createAnimatedValue, createMotion, motions, Easing, LayoutAnimation, AnimatedNode, AnimatedValue } from "nsh";

See Animation for the guide.

#What an animated value can drive

Other style properties take plain values; to animate the layout itself (sizes, positions in the flow), use LayoutAnimation.

#createAnimatedValue

function createAnimatedValue(value?: number): AnimatedValue;

Creates an animated value starting at value (default 0). Rust: animated_value(value), a Copy handle kept by the component that made it.

use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let x = animated_value(0.0);
    let right = stored(false);
    let toggle = move || {
        let to_right = !right.get();
        right.replace(to_right);
        let _ = x.spring(if to_right { 200.0 } else { 0.0 }, Spring::default());
    };
    view()
        .flex_1()
        .p_6()
        .pt_12()
        .gap_4()
        .child(view().size(px(60.0)).rounded(px(12.0)).bg(rgb(0x6366f1)).bind_translate_x(&x))
        .child(text("Move").on_press(toggle))
}

import { mount, Text, View } from "nsh";
import { createAnimatedValue } from "nsh";

function App() {
  const x = createAnimatedValue(0);
  let right = false;
  const toggle = () => {
    right = !right;
    x.spring(right ? 200 : 0);
  };
  return (
    <View style={{ flex: 1, padding: 24, paddingTop: 48, gap: 16 }}>
      <View style={{ width: 60, height: 60, borderRadius: 12, backgroundColor: "#6366f1", transform: [{ translateX: x }] }} />
      <Text onPress={toggle}>Move</Text>
    </View>
  );
}

mount(App);

#AnimatedValue

class AnimatedValue extends AnimatedNode {
  constructor(value: number);
  set(value: number): void;
  stop(): Promise<number>;
  getValue(): Promise<number>;
  setOffset(offset: number): void;
  flattenOffset(): void;
  extractOffset(): void;
  timing(to: number, options?: { duration?: number; easing?: Easing; delay?: number }): Promise<boolean>;
  spring(to: number, options?: { stiffness?: number; damping?: number; mass?: number; velocity?: number }): Promise<boolean>;
  decay(options?: { velocity?: number; deceleration?: number; clamp?: [number, number]; bounce?: number }): Promise<boolean>;
  keyframes(keyframes: KeyframeValue[], options?: KeyframeTiming): Promise<boolean>;
}

Each animation method returns a promise that resolves with true when the animation finished and false when it was stopped (by stop, set or another animation of the same value). In Rust it returns an AnimationEnd, which a task awaits for the same bool.

let opacity = animated_value(1.0);
spawn(async move {
    if opacity.timing(0.0, 200.0, Easing::EaseInOut).await {
        visible.set(false);
    }
});

const opacity = createAnimatedValue(1);
const finished = await opacity.timing(0, { duration: 200 });
if (finished) visible.set(false);

#AnimatedNode

class AnimatedNode {
  interpolate(config: {
    inputRange: number[];
    outputRange: number[] | string[];
    extrapolate?: Extrapolation;
    extrapolateLeft?: Extrapolation;
    extrapolateRight?: Extrapolation;
    easing?: Easing;
  }): AnimatedNode;
  diffClamp(min: number, max: number, options?: { snap?: boolean }): AnimatedNode;
  add(b: AnimatedNode | number): AnimatedNode;
  sub(b: AnimatedNode | number): AnimatedNode;
  mul(b: AnimatedNode | number): AnimatedNode;
  div(b: AnimatedNode | number): AnimatedNode;
  mod(b: AnimatedNode | number): AnimatedNode;
}

type Extrapolation = "extend" | "clamp" | "identity";

A node of the native animation graph: a AnimatedValue, or a value derived from others. Derived nodes are evaluated on the UI thread whenever their inputs change.

let scroll_y = animated_value(0.0);
let header = scroll_y.diff_clamp(0.0, 44.0);

view()
    .flex_1()
    .child(scroll().scroll_value(&scroll_y).flex_1() /* rows */)
    .child(view().h(px(44.0)).bind_translate_y(&header.mul(-1.0)))

const scroll = createAnimatedValue(0);
const header = scroll.diffClamp(0, 44);

<Scroll scrollValue={scroll} style={{ flex: 1 }}>{/* rows */}</Scroll>
<View style={{ height: 44, transform: [{ translateY: header.mul(-1) }] }} />

let progress = animated_value(0.0);
let rotate = progress.interpolate(&[0.0, 1.0], &[0.0, 360.0]); // degrees, for bind_rotate
let color = progress.interpolate_colors(&[0.0, 0.5, 1.0], &[rgb(0x22c55e), rgb(0xeab308), rgb(0xef4444)]);

const progress = createAnimatedValue(0);
const rotate = progress.interpolate({ inputRange: [0, 1], outputRange: ["0deg", "360deg"] });
const color = progress.interpolate({ inputRange: [0, 0.5, 1], outputRange: ["#22c55e", "#eab308", "#ef4444"] });

#Keyframes

interface Keyframe {
  offset?: number;          // 0..1 of an iteration; missing offsets spread evenly
  value: number | string;   // a number, or an angle ("45deg", "0.5turn") in degrees
  easing?: Easing;          // the segment that starts here
}
type KeyframeValue = number | string | Keyframe;

interface KeyframeTiming {
  duration?: number;        // one iteration, ms (300)
  delay?: number;           // before the first iteration, ms (0)
  easing?: Easing;          // segments without their own (CSS "ease")
  iterations?: number | "infinite";   // 1
  direction?: "normal" | "reverse" | "alternate" | "alternate-reverse";
}

value.keyframes(frames, options) plays a value through keyframes and resolves with whether they finished; Animated.keyframes(value, { keyframes, ...options }) is the same as a step of a composite. Rust: value.keyframes(frames, KeyframeTiming) and Animation::keyframes(&value, frames, KeyframeTiming), with Keyframe::new(value) (spread evenly), Keyframe::at(offset, value) and .ease(easing), and KeyframeTiming::new(ms) with .delay(ms), .easing(e), .iterations(Some(n)), .infinite() and .direction(PlaybackDirection::…).

They play as CSS keyframes play: an easing shapes one segment (a keyframe’s the segment that starts at it, the timing’s every other one); offsets missing from keyframes spread evenly, the first at 0 and the last at 1; each iteration starts with a jump to its first keyframe, and without a keyframe at 0 the value goes from where it is; during a delay the value holds the first keyframe (CSS animation-fill-mode: backwards); backward iterations run the segments backwards with their curves reversed; the value stays where the last iteration leaves it.

let y = animated_value(0.0);
y.keyframes(
    [Keyframe::new(0.0), Keyframe::at(0.3, -20.0).ease(Easing::EaseIn), Keyframe::new(0.0)],
    KeyframeTiming::new(600.0).iterations(Some(3)),
);

const y = createAnimatedValue(0);
y.keyframes([0, { offset: 0.3, value: -20, easing: "easeIn" }, 0], { duration: 600, iterations: 3 });

#createMotion

function createMotion(options?: MotionOptions): Motion;

interface MotionOptions extends MotionPlayOptions {
  initial?: { [C in MotionChannel]?: number };   // where channels start (the others at rest)
  enter?: MotionName | MotionSpec;   // start where it starts and play it at once
}

interface MotionPlayOptions extends KeyframeTiming {
  ignoreReduceMotion?: boolean;      // play even when the user asks for less motion
}

interface Motion {
  readonly opacity: AnimatedValue;
  readonly translateX: AnimatedValue;
  readonly translateY: AnimatedValue;
  readonly rotate: AnimatedValue;    // degrees
  readonly rotateX: AnimatedValue;
  readonly rotateY: AnimatedValue;
  readonly scale: AnimatedValue;
  readonly scaleX: AnimatedValue;
  readonly scaleY: AnimatedValue;
  readonly style: { opacity: AnimatedValue; transform: MotionTransform };
  readonly transform: MotionTransform;
  play(motion: MotionName | MotionSpec, options?: MotionPlayOptions): Promise<boolean>;
  animation(motion: MotionName | MotionSpec, options?: MotionPlayOptions): CompositeAnimation;
  stop(): void;
  reset(): void;
}

Creates a motion: an animated value for each channel of a view’s opacity and transform, at rest (opacity and scales 1, the others 0), and motions to play on them natively. Bind it with style={motion.style}, or spread motion.style or motion.transform into a style; the transform applies its translations, then its rotations, then its scales, with scale folded into scaleX and scaleY: 7 of a view’s 8 transform steps, which leaves one for yours ([{ perspective: 600 }, ...motion.transform] for 3D flips). initial sets where channels start ({ opacity: 0 }; the others start at rest). With enter, the channels it moves start where that motion starts (over initial) and it plays at once, with the other options as its timing (delay, duration, …). A motion moves opacity and transform only: spreading motion.style sets the view’s opacity, so bind only motion.transform to keep an opacity of your own, and move colors with an animated value and interpolate. Rust: motion(), a Copy handle kept by the component that made it, bound with .bind_motion(&m); motion().entering(spec) enters.

When the user asks for less motion (reduceMotion()), play, animation and enter land where the motion ends at once, without moving, unless ignoreReduceMotion is set (on the options or the motion).

let card = motion().entering(MotionPreset::FadeInUp.spec().timing(|t| t.delay(80.0)));
view().size(px(120.0)).rounded(px(16.0)).bg(rgb(0x0969da)).bind_motion(&card).on_press(move || {
    card.play(MotionPreset::Pulse);
})

const card = createMotion({ enter: "fadeInUp", delay: 80 });
<View onPress={() => card.play("pulse")} style={{ width: 120, height: 120, borderRadius: 16, backgroundColor: "#0969da", ...card.style }} />

#motions

const motions: Readonly<Record<MotionName, MotionPreset>>;

type MotionChannel = "opacity" | "translateX" | "translateY" | "rotate" | "rotateX" | "rotateY" | "scale" | "scaleX" | "scaleY";

interface MotionSpec extends KeyframeTiming {
  keyframes: { [C in MotionChannel]?: KeyframeValue[] } | MotionFrame[];
  ignoreReduceMotion?: boolean;
}
type MotionFrame = { [C in MotionChannel]?: number | string } & { offset?: number; easing?: Easing };

interface MotionPreset extends MotionSpec {
  kind: "enter" | "exit" | "attention" | "loop";
}

The ready-made motions as data: motion.play("shake") plays motions.shake. MotionName is one of fadeIn, fadeInUp, fadeInDown, fadeInLeft, fadeInRight, zoomIn, popIn, bounceIn, slideInUp, slideInDown, flipInX, flipInY (enter); fadeOut, fadeOutUp, fadeOutDown, fadeOutLeft, fadeOutRight, zoomOut, popOut, slideOutDown, slideOutUp (exit); shake, headShake, wiggle, swing, pulse, heartbeat, rubberBand, jello, tada, jump, flash (attention); spin, float, breathe, sway, bob, glow (loop). Animation describes each one. Spread a preset to change it: motion.play({ ...motions.fadeInUp, duration: 600 }).

A MotionSpec is a motion of your own: each channel’s keyframes ({ opacity: [0, 1], translateY: [24, 0] }), or a list of frames as the Web Animations API writes them ([{ opacity: 0, translateY: 24 }, { opacity: 1, translateY: 0 }], a frame without an offset placed by its position in the list), with the keyframe timing. Rust: MotionSpec::new(KeyframeTiming) with .values(channel, values) (spread evenly), .track(channel, keyframes) and .timing(|t| …); MotionPreset::FadeInUp (or .spec()) is a preset, and MotionChannel names the channels.

let rise = MotionSpec::new(KeyframeTiming::new(400.0))
    .values(MotionChannel::Opacity, [0.0, 1.0])
    .track(MotionChannel::TranslateY, [Keyframe::at(0.0, 24.0).ease(Easing::EaseOut), Keyframe::at(1.0, 0.0)]);
card.play(rise);

card.play({ duration: 400, keyframes: [{ opacity: 0, translateY: 24, easing: "easeOut" }, { opacity: 1, translateY: 0 }] });

#Animated

const Animated: {
  timing(value: AnimatedValue, config: { toValue: number; duration?: number; easing?: Easing; delay?: number }): CompositeAnimation;
  spring(value: AnimatedValue, config: { toValue: number; stiffness?: number; damping?: number; mass?: number; velocity?: number }): CompositeAnimation;
  decay(value: AnimatedValue, config?: { velocity?: number; deceleration?: number; clamp?: [number, number]; bounce?: number }): CompositeAnimation;
  sequence(list: CompositeAnimation[]): CompositeAnimation;
  parallel(list: CompositeAnimation[], config?: { stopTogether?: boolean }): CompositeAnimation;
  stagger(ms: number, list: CompositeAnimation[], config?: { from?: "first" | "last" | "center" | number }): CompositeAnimation;
  delay(ms: number): CompositeAnimation;
  loop(animation: CompositeAnimation, config?: { iterations?: number; resetBeforeIteration?: boolean }): CompositeAnimation;
  keyframes(value: AnimatedValue, config: KeyframeTiming & { keyframes: KeyframeValue[] }): CompositeAnimation;
  add(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  subtract(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  multiply(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  divide(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  modulo(a: AnimatedNode, b: AnimatedNode | number): AnimatedNode;
  diffClamp(a: AnimatedNode, min: number, max: number, options?: { snap?: boolean }): AnimatedNode;
  sampleSpring(config: SpringConfig & { from?: number }, fps?: number): number[];
  sampleDecay(config: DecayConfig & { from?: number }, fps?: number): number[];
};

interface CompositeAnimation {
  start(callback?: (result: { finished: boolean }) => void): Promise<boolean>;
  stop(): void;
  reset(): void;
}

Animated builds animations out of steps (timing, spring, decay, sequence, parallel, …). Nothing runs until start(); then the whole tree runs natively, and each step starts on the UI thread at the exact moment the previous one ends (no frame gap, no round trip to the app’s code between steps). Rust builds the same tree with Animation.

CompositeAnimation:

let ys: Vec<AnimatedValue> = (0..4).map(|_| animated_value(0.0)).collect();
let hop = Animation::stagger(
    80.0,
    ys.iter().map(|y| {
        Animation::sequence([
            Animation::timing(y, -36.0, Timing::new(220.0, Easing::Curve(Curve::Quad, EaseMode::Out))),
            Animation::spring(y, 0.0, Spring { stiffness: 300.0, damping: 12.0, ..Spring::default() }),
        ])
    }),
);
let run = hop.start();
spawn(async move { log::info!("{}", if run.await { "done" } else { "stopped" }) });

const ys = [0, 1, 2, 3].map(() => createAnimatedValue(0));
const hop = Animated.stagger(
  80,
  ys.map((y) =>
    Animated.sequence([
      Animated.timing(y, { toValue: -36, duration: 220, easing: Easing.out(Easing.quad) }),
      Animated.spring(y, { toValue: 0, stiffness: 300, damping: 12 }),
    ]),
  ),
);
hop.start(({ finished }) => console.log(finished ? "done" : "stopped"));

#Easing

type Easing =
  | "linear" | "ease" | "easeIn" | "easeOut" | "easeInOut"
  | [number, number, number, number]   // cubic Bézier x1, y1, x2, y2
  | EasingCurve
  | EasingSteps;                     // Easing.steps(…)

const Easing: {
  linear: Easing;
  ease: Easing;
  bezier(x1: number, y1: number, x2: number, y2: number): Easing;
  steps(count: number, position?: "jump-start" | "jump-end" | "jump-none" | "jump-both" | "start" | "end"): EasingSteps;
  in(e: Easing): Easing;
  out(e: Easing): Easing;
  inOut(e: Easing): Easing;
  sample(easing: Easing, count: number): number[];
  quad: EasingCurve;
  cubic: EasingCurve;
  poly(n?: number): EasingCurve;
  sin: EasingCurve;
  circle: EasingCurve;
  exp: EasingCurve;
  elastic(bounciness?: number): EasingCurve;
  back(s?: number): EasingCurve;
  bounce: EasingCurve;
};

An easing is data, not a function of the app’s: the runtime evaluates it natively. In Rust it is the enum Easing: Linear, EaseIn, EaseOut, EaseInOut, Bezier(x1, y1, x2, y2), Steps(count, StepPosition) and Curve(curve, mode), with a Curve (Quad, Cubic, Poly(n), Sin, Circle, Exp, Elastic(bounciness), Back(s), Bounce) and an EaseMode (In, Out, InOut). To draw one, Easing.sample(easing, count) (Rust: nsh_core::element::sample_easing) gives its values at count evenly spaced points from 0 to 1; Animated.sampleSpring and Animated.sampleDecay (sample_spring, sample_decay) give a spring’s or decay’s values one per frame (at fps, 60 by default) from from (0) until it ends. All three come from the native code the animations run. Wherever an Easing is accepted in TSX you can pass a name ("easeOut"), a cubic Bézier as four numbers, or a curve from the Easing object.

Easing.steps(count, position) is CSS steps(): the value jumps between count levels instead of moving (a frame-by-frame sprite, a ticking hand). position says where the jumps fall: "jump-end" (the default, also "end"), "jump-start" ("start"), "jump-none" or "jump-both"; Rust: Easing::Steps(count, StepPosition::JumpEnd), JumpStart, JumpNone, JumpBoth.

The curves are in their “in” form (slow at the start). Easing.out(curve) reverses one, Easing.inOut(curve) makes it symmetric, Easing.in(curve) keeps it as is; in Rust that is the EaseMode of Easing::Curve.

let _ = value.timing(1.0, 600.0, Easing::Curve(Curve::Back(1.70158), EaseMode::Out));
let _ = value.timing_with(1.0, Timing { easing: Easing::Bezier(0.2, 0.0, 0.0, 1.0), ..Timing::default() });
let _ = value.timing_with(1.0, Timing { easing: Easing::EaseOut, ..Timing::default() });

value.timing(1, { duration: 600, easing: Easing.out(Easing.back()) });
value.timing(1, { easing: Easing.bezier(0.2, 0, 0, 1) });
value.timing(1, { easing: "easeOut" });

#LayoutAnimation

const LayoutAnimation: {
  configureNext(config: LayoutAnimationConfig, onEnd?: () => void): void;
  create(duration: number, type?: LayoutAnimationType, property?: LayoutAnimationProperty): LayoutAnimationConfig;
  Types: { easeInEaseOut; spring; linear; easeIn; easeOut; keyboard };
  Properties: { opacity; scaleXY };
  Presets: { easeInEaseOut: LayoutAnimationConfig; linear: LayoutAnimationConfig; spring: LayoutAnimationConfig };
  easeInEaseOut(onEnd?: () => void): void;
  linear(onEnd?: () => void): void;
  spring(onEnd?: () => void): void;
};

interface LayoutAnimationConfig {
  duration: number;                // ms
  create?: LayoutAnimationAnimation;    // views inserted
  update?: LayoutAnimationAnimation;    // views moved or resized
  delete?: LayoutAnimationAnimation;    // views removed
}

interface LayoutAnimationAnimation {
  type?: "easeInEaseOut" | "spring" | "linear" | "easeIn" | "easeOut" | "keyboard";
  property?: "opacity" | "scaleXY" | "scale";
  duration?: number;
  delay?: number;
  springDamping?: number;          // 0..1, default 0.7
}

LayoutAnimation.configureNext(config) animates the layout changes of the next commit natively: views that move or resize glide to their new frames, new views appear (fading or scaling in, by property) and removed views disappear. Call it right before the state change that changes the layout. Rust: animate_layout(LayoutAnimation), with nsh_core::element::LayoutAnimation’s presets or its create, update and delete transitions.

let open = signal(false);
let toggle = move || {
    animate_layout(LayoutAnimation::SPRING);
    open.update(|o| *o = !*o);
};

view()
    .child(text("Details").on_press(toggle))
    .child(when(move || open.get(), || text("Shown with a spring.")))

const open = signal(false);
const toggle = () => {
  LayoutAnimation.configureNext(LayoutAnimation.Presets.spring);
  open.update((o) => !o);
};

<View>
  <Text onPress={toggle}>Details</Text>
  <If when={open()}>
    <Text>Shown with a spring.</Text>
  </If>
</View>

#Device

The device API tells the app about the device and its environment. Rust code calls the functions of nsh_core::prelude (window(), dark(), font_scale(), locale(), os(), idiom(), pixel_ratio(), set_color_scheme(), …); TSX imports them from nsh. The window size, the color scheme, the font scale, the pixel ratio and the locale are reactive: read them in a binding (a closure passed to an element in Rust, JSX in TSX), computed or effect, and what reads them updates when the platform reports a change (rotation, a window resize, switching to dark mode, changing the text size or the language, moving to a screen of another density).

use nsh_core::{
    platform::{Appearance, Idiom, Os},
    prelude::*, // window, dark, font_scale, locale, os, idiom, pixel_ratio, set_color_scheme, ...
};

import { colorScheme, fontScale, locale, openUrl, pixelRatio, platform, setColorScheme, windowSize } from "nsh";

See Device and environment for the guide.

#windowSize

const windowSize: Accessor<Size>;

The size of the surface in points: the window, or the embedded NshAppView / NshView. Reactive. Rust: window() -> Size<Points>.

let wide = move || window().width >= px(600.0);

view().style_when(wide, |s| s.flex_row())

const wide = () => windowSize().width >= 600;

<View style={{ flexDirection: wide() ? "row" : "column" }}>{/* ... */}</View>

#colorScheme

const colorScheme: Accessor<"light" | "dark">;

The appearance shown: the system’s, unless the app set its own (nsh.json "appearance", setColorScheme). Reactive. Rust: dark() -> bool; theme colors (AdaptiveColor) and the .dark(…) style variant follow it without reading it. Tailwind’s dark: variant follows it too (see Tailwind).

view().flex_1().bg(move || if dark() { black() } else { white() })

const dark = () => colorScheme() === "dark";

<View style={{ flex: 1, backgroundColor: dark() ? "#000" : "#fff" }} />

#fontScale

const fontScale: Accessor<number>;

The user’s preferred text size relative to the default (1 is the default size; Dynamic Type on iOS, font size on Android), or the text size the embedding app sets in its place. Reactive. Rust: font_scale() -> f32. Text already scales with it unless allowFontScaling={false}; read it when other sizes should follow, such as icons next to text.

#locale

const locale: Accessor<string>;

The user’s locale as a BCP 47 tag ("en-US", "zh-Hans-CN"), or the locale the embedding app sets in its place. Reactive. Rust: locale() -> Locale (locale().as_str() is the tag). Intl formats for it by default; read it to choose the strings of your own translations (Device and environment).

#setColorScheme

function setColorScheme(scheme: "light" | "dark" | "system"): void;

Shows the app in scheme whatever the system’s appearance, at once: colorScheme(), dark: classes, the components’ theme and the platform’s controls (alerts, the status bar’s default style) follow it; "system" follows the system again. nsh.json "appearance" sets it from the start. Rust: set_color_scheme(Appearance::Dark) (Appearance::Light, Appearance::System).

#platform

const platform: Platform;

interface Platform {
  readonly os: "ios" | "android" | "macos" | "windows" | "linux" | "web";
  readonly version: string;
  readonly idiom: "phone" | "pad" | "mac" | "tv" | "desktop";
  readonly catalyst: boolean;
  select<T>(spec: PlatformSelectSpec<T>): T | undefined;
}

The platform the app runs on, constant while it runs.

let columns = if is_desktop() { 3 } else { 1 };

const columns = platform.idiom === "desktop" ? 3 : 1;

#platform.select

interface PlatformSelectSpec<T> {
  ios?: T;
  android?: T;
  macos?: T;
  windows?: T;
  linux?: T;
  web?: T;
  mobile?: T;   // iOS, Android, and phone and tablet browsers
  desktop?: T;  // macOS, Windows, Linux, and desktop browsers
  native?: T;   // every platform but the web
  default?: T;
}

Returns the value for the current OS (ios, android, web, …), else mobile / desktop, else native (every platform but the web), else default, else undefined. In a browser, mobile or desktop follows the idiom. Rust code matches on os() (and is_desktop() for mobile / desktop).

use nsh_core::platform::Os;

let card = view().p_4();
let card = match os() {
    Os::Ios => card.shadow_color(black()).shadow_opacity(0.15).shadow_radius(px(8.0)),
    Os::Android => card.elevation(px(4.0)),
    _ => card,
};

const shadow = platform.select({
  ios: { shadowColor: "#000", shadowOpacity: 0.15, shadowRadius: 8 },
  android: { elevation: 4 },
});

#pixelRatio

const pixelRatio: Accessor<number>;

Device pixels per point (e.g. 3 on most iPhones). Reactive: it changes when the window moves to a screen of another density (on Mac Catalyst, the desktops, or an external display). Rust: pixel_ratio() -> f32, and round_to_nearest_pixel(points) for a length on whole device pixels; in TSX that length is Math.round(x * pixelRatio()) / pixelRatio().

let hairline = move || px(1.0 / pixel_ratio());

const hairline = () => 1 / pixelRatio();

#openUrl

function openUrl(url: string): Promise<boolean>;

Opens url outside the app: a web page in the browser, a mailto: link in the mail app, a tel: link in the phone app, and any scheme another app registered (maps:, a host app’s own lb:// links). It resolves to whether something opened it: false when no app handles the scheme. Rust: open_url(url) of nsh_core::prelude, an answer to await in a task (or to drop).

button()
    .child(text("Contact us"))
    .on_press(|| {
        spawn(async {
            if !open_url("mailto:help@example.com").await {
                log::warn!("no mail app");
            }
        });
    })

<Button
  onPress={async () => {
    if (!(await openUrl("mailto:help@example.com"))) {
      console.warn("no mail app");
    }
  }}
>
  <Text>Contact us</Text>
</Button>

• The URL is absolute (it has a scheme). URLs that would run code or reach the app’s own data, javascript:, data:, blob:, file:, about: and asset:, throw a TypeError, as do relative addresses.
• An app that declares capabilities needs openUrl: "openUrl": true for every scheme, or "openUrl": { "schemes": ["https", "mailto"] } for those listed; other URLs throw a TypeError (see Sandbox and capabilities).
• The embedding app sees the URL first and can route it through its own router instead (Swift NshAppView.onOpenURL, Java NshView.setOpenUrlHandler, Rust AppView::host().handle_open_url; see iOS and Android). The promise then resolves to true.
• Each platform opens it with its own opener: UIApplication.open on iOS (the host app’s application when embedded), an ACTION_VIEW intent on Android, NSWorkspace on macOS, ShellExecuteW on Windows, GtkUriLauncher on Linux, GPUI’s open_url, a new tab on the web. nsh test records the URLs instead of opening them.
• A TextView opens its links this way with links="open".

#Layout direction

The layout direction follows the user’s language: in a right-to-left language (Arabic, Hebrew, …) the app lays out right to left, rows run from the right, and left / right style properties (marginLeft, paddingRight, …) mean start and end. Changes apply at once, with no restart.

A view’s direction style ("ltr", "rtl" or "inherit", the default) sets the direction of its own subtree; in Rust, .direction(LayoutDirection::..).

view().direction(LayoutDirection::Rtl).flex_row().gap_2().child(text("First")).child(text("Second"))

<View style={{ direction: "rtl", flexDirection: "row", gap: 8 }}>
  <Text>First</Text>
  <Text>Second</Text>
</View>

#Related

• Safe area insets (Rust safe_area(); TSX safeArea(), safeAreaInsets()) and the software keyboard (Rust keyboard_height(); TSX keyboardFrame()) are in Safe area and keyboard.
• Screen reader and reduced motion settings are in Accessibility.

#PanResponder

Pan responders are drag gestures on top of the gesture responder system: the element claims the touches of a gesture, then hears them alone with the gesture state, which tracks the touches’ centroid, the distance moved and the velocity for you. Rust code claims them with .claim_touches(TouchClaim::…) and hears them with .on_responder_* listeners whose ResponderEvent carries a PanGesture, all in nsh_core::prelude; TSX imports PanResponder from nsh, whose onPanResponder… callbacks receive the touch event and the gesture state.

use nsh_core::prelude::*; // TouchClaim, ClaimRequest, ResponderEvent, PanGesture

import { PanResponder, type PanResponderGestureState } from "nsh";

#PanResponder.create

const PanResponder: { create(config: PanResponderCallbacks): PanResponderInstance };

interface PanResponderInstance {
  panHandlers: TouchProps;
}

Creates a pan responder. Spread its panHandlers on the view that should receive the gesture. In Rust, the view claims the touches and listens itself:

use nsh_core::prelude::*;

#[component]
pub fn App() -> impl IntoElement {
    let pos = signal((0.0_f32, 0.0_f32));
    let start = stored((0.0_f32, 0.0_f32));
    view().flex_1().child(
        view()
            .size(px(64.0))
            .rounded(px(32.0))
            .bg(rgb(0x6366f1))
            .style_with(move |s| {
                let (x, y) = pos.get();
                s.translate_x(px(x)).translate_y(px(y))
            })
            .claim_touches(TouchClaim::on_start())
            .on_responder_grant(move |_: &ResponderEvent| {
                start.replace(pos.get_untracked());
            })
            .on_responder_move(move |e: &ResponderEvent| {
                let (x, y) = start.get();
                pos.set((x + e.gesture.delta.x.0, y + e.gesture.delta.y.0));
            })
            .on_responder_release(move |e: &ResponderEvent| {
                log::info!("released at {:.2} pt/ms", e.gesture.vx);
            }),
    )
}

import { mount, signal, View } from "nsh";
import { PanResponder } from "nsh";

function App() {
  const pos = signal({ x: 0, y: 0 });
  let start = { x: 0, y: 0 };
  const pan = PanResponder.create({
    onStartShouldSetPanResponder: () => true,
    onPanResponderGrant: () => (start = pos()),
    onPanResponderMove: (_, g) => pos.set({ x: start.x + g.dx, y: start.y + g.dy }),
    onPanResponderRelease: (_, g) => console.log(`released at ${g.vx.toFixed(2)} pt/ms`),
  });
  return (
    <View style={{ flex: 1 }}>
      <View
        {...pan.panHandlers}
        style={{
          width: 64,
          height: 64,
          borderRadius: 32,
          backgroundColor: "#6366f1",
          transform: [{ translateX: pos().x }, { translateY: pos().y }],
        }}
      />
    </View>
  );
}

mount(App);

#Callbacks

Every callback receives the touch event (GestureResponderEvent, from nsh) and the gesture state. In Rust, a claim decides with .ask(|request: &ClaimRequest| …), calling request.claim() to take the touches (without ask it takes them always), and each listener gets a ResponderEvent whose gesture is the state.

type PanHandler<R = void> = (e: GestureResponderEvent, gestureState: PanResponderGestureState) => R;

#PanResponderGestureState

interface PanResponderGestureState {
  stateID: number;
  moveX: number;               // latest centroid of the touches (surface points)
  moveY: number;
  x0: number;                  // the centroid when the responder was granted
  y0: number;
  dx: number;                  // distance moved since the grant
  dy: number;
  vx: number;                  // velocity, points per millisecond
  vy: number;
  numberActiveTouches: number;
}

Rust: PanGesture, with points as Point<Points>.

#Inside scroll views

While a pan responder is the responder, native scroll views around it do not scroll (onShouldBlockNativeResponder defaults to true). To let a horizontal swipe coexist with vertical scrolling, become the responder only on horizontal moves:

view()
    .claim_touches(TouchClaim::on_move().ask(|request: &ClaimRequest| {
        let d = request.event.gesture.delta;
        if d.x.0.abs() > 10.0 && d.x.0.abs() > d.y.0.abs() {
            request.claim();
        }
    }))
    .on_responder_move(move |e: &ResponderEvent| offset.set(e.gesture.delta.x.0))
    .on_responder_release(move |e: &ResponderEvent| {
        if e.gesture.delta.x.0.abs() > 120.0 { remove() } else { offset.set(0.0) }
    })
    .on_responder_terminate(move |_: &ResponderEvent| offset.set(0.0))

const swipe = PanResponder.create({
  onMoveShouldSetPanResponder: (_, g) => Math.abs(g.dx) > 10 && Math.abs(g.dx) > Math.abs(g.dy),
  onPanResponderMove: (_, g) => offset.set(g.dx),
  onPanResponderRelease: (_, g) => (Math.abs(g.dx) > 120 ? remove() : offset.set(0)),
  onPanResponderTerminate: () => offset.set(0),
});

For a pan the platform recognizes, TouchClaim::on_pan(PanActivation::horizontal(10.0, 10.0)) decides on the main thread as the fingers move. The underlying responder props (onStartShouldSetResponder, onResponderGrant, onTouchStart, …) can also be used directly on any element; see Elements.

#Clipboard

The clipboard API reads and writes the system clipboard: text everywhere (UIPasteboard on iOS, ClipboardManager on Android, NSPasteboard, GDK and the Win32 clipboard on desktops, navigator.clipboard on the web), images on iOS, the desktops and the web, and the files copied in a file manager on the desktops and Mac Catalyst. Rust code calls the functions of nsh_core::prelude (set_clipboard, clipboard_string, …); TSX imports Clipboard from nsh.

use nsh_core::prelude::*; // set_clipboard, clipboard_string, clipboard_image, ...
use nsh_core::element::ClipboardImage;

import { Clipboard } from "nsh";

const Clipboard: {
  writeText(text: string): Promise<void>;
  readText(): Promise<string>;
  hasText(): Promise<boolean>;
  writeImage(src: string): Promise<void>;
  readImage(): Promise<ClipboardImage | null>;
  hasImage(): Promise<boolean>;
  readFiles(): Promise<string[]>;
};

interface ClipboardImage {
  url: string; // data:image/png;base64,…
  size: { width: number; height: number }; // pixels
}

The Rust reads return answers to await in a task (spawn, or an async module function); ClipboardImage is nsh_core::element::ClipboardImage, with url and size (a Size<DevicePixels>).

The user can also copy from a selectable text themselves; the clipboard API is for copying from code, such as a Copy button.

#Clipboard.writeText

writeText(text: string): Promise<void>;

Puts text on the clipboard, replacing what was there. Rust: set_clipboard(text).

use nsh_core::prelude::*;

fn copy_button(code: Signal<String>) -> impl IntoElement {
    let copied = signal(false);
    view()
        .role(AccessibilityRole::Button)
        .on_press(move || {
            set_clipboard(code.get());
            copied.set(true);
        })
        .child(text(move || if copied.get() { "Copied" } else { "Copy" }))
}

import { signal, Text, View } from "nsh";
import { Clipboard } from "nsh";

const copied = signal(false);

<View
  onPress={async () => {
    await Clipboard.writeText(code());
    copied.set(true);
  }}
>
  <Text>{copied() ? "Copied" : "Copy"}</Text>
</View>;

#Clipboard.readText

readText(): Promise<string>;

Resolves with the clipboard’s text, or "" when it holds none. Rust: clipboard_string(). On iOS, reading the clipboard can show the system’s paste notice (“App pasted from …”), and on Android 10 and later only the app in the foreground can read it. Read it when the user asks to paste, not on every screen.

spawn(async move {
    let pasted = clipboard_string().await;
    if !pasted.is_empty() {
        code.set(pasted.trim().to_string());
    }
});

const pasted = await Clipboard.readText();
if (pasted) code.set(pasted.trim());

#Clipboard.hasText

hasText(): Promise<boolean>;

Resolves with whether the clipboard holds text, without reading it: no paste notice on iOS. Rust: clipboard_has_string(). Use it to decide whether to show a Paste button. On the web, browsers only tell by reading, so it may ask the user for permission.

let can_paste = signal(false);
spawn(async move { can_paste.set(clipboard_has_string().await) });

const canPaste = signal(false);
Clipboard.hasText().then((has) => canPaste.set(has));

#Clipboard.readImage

readImage(): Promise<ClipboardImage | null>;

Resolves with the clipboard’s image, or null when it holds none: a pasted screenshot, or an image copied in a browser or an image editor. Rust: clipboard_image(), None when it holds none. url is a data: URL of the image (PNG, or the clipboard’s own JPEG, GIF, WebP or BMP), which an Image shows as its src; in TSX, fetch(url) gives its bytes, for an upload, and in Rust the base64 after the comma decodes to them. size (width and height) is its size in pixels. As with readText, read it when the user asks to paste. Images of up to 48 MB (encoded) are read, so the data: URL fits in the app’s memory; for a larger one readImage resolves null and hasImage true.

use base64::Engine as _;
use nsh_core::{element::ClipboardImage, prelude::*};

fn attachments() -> impl IntoElement {
    let attachments = signal(Vec::<ClipboardImage>::new());
    let paste = move || {
        spawn(async move {
            if let Some(image) = clipboard_image().await {
                attachments.update(|list| list.push(image));
            }
        });
    };
    view()
        .flex_row()
        .gap_2()
        .child(text("Paste").on_press(paste))
        .child(each(
            attachments,
            |shot: &ClipboardImage| shot.url.clone(),
            |shot, _| image(move || shot.with(|s| s.url.clone())).size(px(64.0)).rounded(px(8.0)),
        ))
}

async fn upload(image: &ClipboardImage) -> Result<HttpResponse, String> {
    let (_, data) = image.url.split_once(',').ok_or("not a data: URL")?;
    let bytes = base64::engine::general_purpose::STANDARD
        .decode(data)
        .map_err(|e| e.to_string())?;
    let request = HttpRequest::post("https://example.com/upload", bytes).header("Content-Type", "image/png");
    fetch(request).await
}

import { Image, signal, View } from "nsh";
import { Clipboard, type ClipboardImage } from "nsh";

const attachments = signal<ClipboardImage[]>([]);

async function paste() {
  const image = await Clipboard.readImage();
  if (image) attachments.set([...attachments(), image]);
}

async function upload(image: ClipboardImage) {
  const body = new FormData();
  body.append("file", await (await fetch(image.url)).blob(), "screenshot.png");
  await fetch("https://example.com/upload", { method: "POST", body });
}

<View class="flex-row gap-2">
  <Each of={attachments()}>
    {(image) => <Image src={image().url} style={{ width: 64, height: 64, borderRadius: 8 }} />}
  </Each>
</View>;

A chat-style app where users paste screenshots into a composer binds the paste shortcut while its input has the focus and takes the image when there is one:

use nsh_core::keymap::When;

on_key_with("mod+v", KeyOptions { when: When::Always, ..KeyOptions::default() }, move |_| {
    spawn(async move {
        if clipboard_has_image().await {
            paste().await;
        } else {
            insert_text(&clipboard_string().await);
        }
    });
});

import { keymap } from "nsh";

keymap.bind("mod+v", async () => {
  if (await Clipboard.hasImage()) return paste();
  insertText(await Clipboard.readText());
}, { when: "always" });

#Clipboard.hasImage

hasImage(): Promise<boolean>;

Resolves with whether the clipboard holds an image, without reading it: no paste notice on iOS. Rust: clipboard_has_image().

#Clipboard.writeImage

writeImage(src: string): Promise<void>;

Puts the image of src, a base64 data: URL such as readImage gives, on the clipboard, replacing what it holds. Rust: set_clipboard_image(src). On Windows it takes a PNG, the format browsers, Office and the Snipping Tool read.

set_clipboard_image(image.url.clone());

await Clipboard.writeImage(image.url);

#Clipboard.readFiles

readFiles(): Promise<string[]>;

Resolves with the file: URLs of the files and folders copied in a file manager (Finder, Explorer, Files), in their order, or []: the same URLs a file drop gives. Rust: clipboard_files(). Parse a URL to get its path.

let paths: Vec<std::path::PathBuf> = clipboard_files()
    .await
    .iter()
    .filter_map(|file| url::Url::parse(file).ok()?.to_file_path().ok())
    .collect();

const files = await Clipboard.readFiles();
const names = files.map((url) => decodeURIComponent(new URL(url).pathname.split("/").pop()!));

#Picker

The picker API shows the system’s picker for photos and gives the app the images the user picks: the Photos picker on iOS (PHPickerViewController), the Photo Picker on Android, an open panel or file dialog on the desktops and a file input in a browser. On iOS and Android the picker runs outside the app and hands over only what the user picks, so it needs no photo library permission. Each picked image arrives as a File (TSX) or a PickedFile (Rust) whose bytes stay native: show it with URL.createObjectURL(file) in an Image, upload it with fetch and FormData. Rust code calls pick_images of nsh_core::prelude; TSX imports Picker from nsh.

use nsh_core::picker::{PickRequest, PickedFile};
use nsh_core::prelude::*; // pick_images

import { Picker, type PickedImage } from "nsh";

const Picker: {
  pickImages(options?: PickImagesOptions): Promise<PickedImage[]>;
};

interface PickImagesOptions {
  multiple?: boolean; // let the user pick several (false: one)
  limit?: number; // at most this many when multiple (up to 100)
  maxDimension?: number; // scale images whose longer side is longer, in pixels
  quality?: number; // JPEG quality from 0 to 1 (0.9)
  format?: "compatible" | "current"; // "compatible": HEIC and the like as JPEG
}

interface PickedImage {
  file: File; // name, type, size in bytes and the bytes
  size: { width: number; height: number }; // pixels, upright
}

#Picker.pickImages

pickImages(options?: PickImagesOptions): Promise<PickedImage[]>;

Shows the picker and resolves with the images the user picked, in the order picked, or [] when the user cancels. Rust: pick_images(request), an answer to await in a task (spawn, or an async module function). Options out of range (limit: 0, a quality outside 0 to 1) throw a RangeError in the call.

The images come ready to send:

• Formats every browser and server take. JPEG, PNG, GIF and WebP come as they are; a photo stored in another format (HEIC on iPhones, HEIF, TIFF) comes as a JPEG. format: "current" keeps the stored format.
• Scaled down natively. With maxDimension, an image whose longer side is longer is scaled to fit it, upright, and encoded again: a PNG as a PNG, anything else as a JPEG of quality. Phone photos are 12 to 48 megapixels; scaling them to 2048 pixels before an upload makes them a few hundred kilobytes. A quality encodes JPEGs again too.
• What it shows. size is the image’s size in pixels as it shows, its camera orientation applied. An image NSH encodes again carries no metadata (no location); one that comes as it is keeps its own.

On Windows, Linux and in GPUI windows, the dialog offers the formats the request takes (with "compatible": JPEG, PNG, GIF and WebP) and the files come as they are stored, at their own size.

A chat composer attaches a photo, shows it while the message is written, and uploads it when it is sent:

use nsh_core::geometry::{DevicePixels, Percentage};
use nsh_core::picker::{PickRequest, PickedFile};
use nsh_core::prelude::*;

fn attach_button(attached: Signal<Option<PickedFile>>) -> impl IntoElement {
    view()
        .role(AccessibilityRole::Button)
        .accessibility_label("Choose a photo")
        .on_press(move || {
            let mut request = PickRequest::new(false, 1);
            request.max_dimension = Some(DevicePixels(2048));
            request.quality = Some(Percentage(0.85));
            let picked = pick_images(request);
            spawn(async move {
                if let Some(file) = picked.await.into_iter().next() {
                    attached.set(Some(file));
                }
            });
        })
        .child(text("Photo"))
}

async fn upload(file: &PickedFile) -> Result<HttpResponse, String> {
    let request = HttpRequest::post("https://example.com/upload", file.data.to_vec())
        .header("Content-Type", file.mime.as_str());
    fetch(request).await
}

import { Image, signal, Text, View } from "nsh";
import { Picker } from "nsh";

const attached = signal<{ file: File; src: string } | null>(null);

async function choosePhoto() {
  const [picked] = await Picker.pickImages({ maxDimension: 2048, quality: 0.85 });
  if (picked) attached.set({ file: picked.file, src: URL.createObjectURL(picked.file) });
}

async function send(text: string) {
  const body = new FormData();
  body.append("text", text);
  if (attached()) body.append("photo", attached()!.file);
  await fetch("https://example.com/messages", { method: "POST", body });
  if (attached()) URL.revokeObjectURL(attached()!.src);
  attached.set(null);
}

<View class="flex-row items-center gap-2">
  <View role="button" accessibilityLabel="Choose a photo" onPress={choosePhoto}>
    <Text>Photo</Text>
  </View>
  <If when={attached()}>
    <Image src={attached()!.src} style={{ width: 48, height: 48, borderRadius: 8 }} />
  </If>
</View>;

Several photos at once:

let picked = pick_images(PickRequest::new(true, 9));
spawn(async move {
    let files = picked.await;
    photos.update(|list| list.extend(files));
});