Installiere Native-UI in unter einer Minute

1. 1

   Paket und Peer-Abhängigkeiten installieren

   npm install @polprog/native-ui react-native-reanimated react-native-safe-area-context
   
   # Optional, for DatePickerInput and DateRangePickerInput
   npm install @react-native-community/datetimepicker

2. 2

   Space Grotesk laden (vom Standard-Theme Aurora verwendet)

   npx expo install @expo-google-fonts/space-grotesk expo-font

3. 3

   App umschließen

   import { NativeUIProvider } from '@polprog/native-ui';
   
   export default function App() {
     return (
       <NativeUIProvider>
         <Root />
       </NativeUIProvider>
     );
   }

4. 4

   Bildschirme zusammensetzen

   import { Button, Card, Heading, VStack } from '@polprog/native-ui';
   
   export function Welcome({ onStart }: { onStart: () => void }) {
     return (
       <Card>
         <VStack gap="lg">
           <Heading level={1}>Welcome</Heading>
           <Button title="Get started" onPress={onStart} />
         </VStack>
       </Card>
     );
   }

Upgrade von 1.x 2.0

Version 2.0 benötigt React 19, React Native 0.84+ und Reanimated 4 und entfernt die in 1.x als veraltet markierten APIs. Die Umbenennungen unten decken die meisten Apps ab. Der Leitfaden listet jede Änderung mit Code vorher und nachher auf.

// 1.x                                  // 2.0
useThemeColors()                      →  useColors()
<Button variant="destructive" />      →  <Button variant="danger" />
<Card longPressHint="…" />            →  <Card accessibilityHint="…" />
<Select selectedValue onValueChange>  →  <Select value onChange>
typography.amount / amountLarge       →  typography.mono / monoLarge

Vollständigen Upgrade-Leitfaden lesen →

Theming

Wechsle sofort zwischen hell, dunkel oder System, oder tausche den gesamten Look mit einer Theme-Variante. Native-UI liefert zwei: Aurora (das Original) und Bloom (weich, abgerundet, violett). Jede Variante bringt eigene Akzent-Presets mit, customAccent überschreibt eine einzelne Farbe, und theme.components überschreibt die Tokens jeder beliebigen Komponente. Du übergibst nur das, was sich ändert.

import { NativeUIProvider, bloomFontFamilies } from '@polprog/native-ui';

export default function App() {
  return (
    <NativeUIProvider
      config={{
        theme: 'bloom',        // 'default' (Aurora) | 'bloom'
        colorMode: 'system',   // 'light' | 'dark' | 'system'
        preset: 'violet',      // accent preset for the active variant
        fontFamilies: bloomFontFamilies,
      }}
    >
      <Root />
    </NativeUIProvider>
  );
}

Akzent-Presets

Design-Tokens

Jede Oberfläche (Farbe, Abstand, Radius, Typografie, Schatten) ist ein benannter Token. Komponenten lesen nur Tokens, daher wirkt sich die Änderung eines Tokens systemweit aus.

import { View } from 'react-native';
import { useTheme } from '@polprog/native-ui';

function Banner() {
  const theme = useTheme();

  return (
    <View
      style={{
        backgroundColor: theme.colors.primaryLight,
        padding: theme.spacing.lg,
        borderRadius: theme.borderRadius.lg,
      }}
    />
  );
}

Barrierefreiheit

Jede interaktive Komponente kommt mit Barrierefreiheits-Defaults: Rollen, Labels, Hit-Slop, Screenreader-Ansagen und Unterstützung für reduzierte Bewegung. Textfarben werden auf jeder Oberfläche gegen den WCAG-Kontrast geprüft (minTextContrast, standardmäßig 4.5, 7 für AAA). Du kannst jeden Default pro Instanz überschreiben.

<NativeUIProvider config={{ minTextContrast: 7 }}>
  <Button
    title="Save"
    accessibilityHint="Saves your changes and moves to the next step"
    onPress={save}
  />
</NativeUIProvider>

Plattformverhalten

Komponenten passen sich an die Host-Plattform an: Haptik, sichere Bereiche, Tastaturverhalten und Dialoge folgen den Konventionen von iOS und Android, InputPrompt nutzt auf iOS den System-Prompt, und Screenreader können Sheets mit ihrer Escape-Geste schließen. Du erhältst Plattform-Korrektheit, ohne Plattform-Code zu schreiben.

// The same sheet on iOS and Android: drag it down to dismiss it.
<BottomSheet visible={open} onClose={() => setOpen(false)}>
  <BottomSheet.Header>
    <Heading level={3}>Choose a plan</Heading>
  </BottomSheet.Header>
  <BottomSheet.Body>
    <PlanList />
  </BottomSheet.Body>
</BottomSheet>

Lokalisierung Neu

Jeder Text, den die Bibliothek rendert, von Button-Hinweisen bis zu Countdown-Einheiten, stammt aus labels. Übergib eine Locale und nur die Labels, die du übersetzt. Der Rest bleibt auf Englisch. Icons und der Zurück-Chevron werden in Rechts-nach-links-Layouts gespiegelt.

<NativeUIProvider
  config={{
    locale: 'pl-PL',
    labels: { close: 'Zamknij', clear: 'Wyczyść', goBack: 'Wróć' },
  }}
>
  <Root />
</NativeUIProvider>

Änderungsprotokoll

1. v2.0.0

   2026-10-29

   Stabil

   Release für Barrierefreiheit, Konfiguration und Robustheit

   • Hinzugefügt

     Accessibility, configuration and robustness release. Breaking: see the "Upgrading to 2.0" guide in Storybook for every change that needs code edits.

     • Removed (deprecated since 1.x): useThemeColors (use useColors), Button variant="destructive" (use danger), typography amount / amountLarge / amountSmall (use mono*), Card longPressHint (use accessibilityHint), Select selectedValue / onValueChange (use value / onChange), unused Select tokens (titlePadding*, cancelPaddingVertical, cancelMarginTop, minBottomPadding).
     • Peer ranges now start at verified versions: React 19, React Native 0.84, Reanimated 4 (required), Safe Area Context 5, DateTimePicker 9.
     • usePressableScale always uses Reanimated; its result no longer has isReanimated and animatedStyle is a Reanimated animated style.
     • Color: new onPrimary, onSuccess, onWarning, onError, onInfo tokens computed with WCAG contrast (minTextContrast, default 4.5). Light-mode primary buttons now use dark text where white was unreadable (1.7:1 on the default green). textInverse is an alias of onPrimary. The default light error is now #DC2626 (white on the old #EF4444 was 3.8:1). getContrastText uses WCAG luminance. New helpers: contrastRatio, resolveOnColor, withAlpha.
     • +18 more…
2. v1.7.2

   2026-10-27

   Stabil

   • Behoben

     Fix type checking against React Native 0.87 and newer. Box and Stack no longer assign to readonly style properties, and the ref of Input, TextArea and SearchBar is typed as the TextInput instance via ComponentRef<typeof TextInput>, which matches older React Native versions as well. Input, TextArea and PressableScale now declare their exported types explicitly, so the published declarations no longer depend on React Native internal type names.

Vollständiges Änderungsprotokoll ansehen →