Zainstaluj Native-UI w mniej niż minutę

1. 1

   Zainstaluj paczkę i jej zależności peer

   npm install @polprog/native-ui react-native-reanimated react-native-safe-area-context
   
   # Opcjonalnie, dla DatePickerInput i DateRangePickerInput
   npm install @react-native-community/datetimepicker

2. 2

   Załaduj Space Grotesk (używany przez domyślny motyw Aurora)

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

3. 3

   Opakuj aplikację

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

4. 4

   Komponuj ekrany

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

Aktualizacja z wersji 1.x 2.0

Wersja 2.0 wymaga React 19, React Native 0.84+ i Reanimated 4 oraz usuwa API oznaczone w 1.x jako przestarzałe. Poniższe zmiany nazw wystarczą w większości aplikacji. Przewodnik opisuje każdą zmianę z kodem przed i po.

// 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

Przeczytaj pełny przewodnik aktualizacji →

Theming

Przełączaj jasny, ciemny lub systemowy błyskawicznie, albo zmień cały wygląd wariantem motywu. Native-UI ma dwa: Aurora (oryginalny) i Bloom (miękki, zaokrąglony, fioletowy). Każdy wariant ma własne presety akcentu, customAccent nadpisuje pojedynczy kolor, a theme.components nadpisuje tokeny dowolnego komponentu. Przekazujesz tylko to, co się zmienia.

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',      // preset akcentu aktywnego wariantu
        fontFamilies: bloomFontFamilies,
      }}
    >
      <Root />
    </NativeUIProvider>
  );
}

Presety akcentu

Tokeny

Każda powierzchnia (kolor, spacing, radius, typografia, cień) to nazwany token. Komponenty czytają wyłącznie tokeny, więc zmiana tokena propaguje się na cały system.

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,
      }}
    />
  );
}

Dostępność

Każdy interaktywny komponent ma domyślne ustawienia dostępności: role, etykiety, hit slop, komunikaty dla czytników ekranu i obsługę ograniczenia ruchu. Kolory tekstu są sprawdzane pod kątem kontrastu WCAG na każdej powierzchni (minTextContrast, domyślnie 4.5, 7 dla AAA). Każde ustawienie domyślne możesz nadpisać dla pojedynczej instancji.

<NativeUIProvider config={{ minTextContrast: 7 }}>
  <Button
    title="Zapisz"
    accessibilityHint="Zapisuje zmiany i przechodzi do następnego kroku"
    onPress={save}
  />
</NativeUIProvider>

Zachowania platformowe

Komponenty dostosowują się do platformy: haptyka, safe area, obsługa klawiatury i okna dialogowe są zgodne z konwencjami iOS i Androida, InputPrompt korzysta na iOS z systemowego promptu, a czytniki ekranu mogą zamykać arkusze gestem wyjścia. Dostajesz poprawne zachowanie na każdej platformie bez pisania kodu specyficznego dla platformy.

// Ten sam arkusz na iOS i Androidzie: przeciągnij go w dół, aby go zamknąć.
<BottomSheet visible={open} onClose={() => setOpen(false)}>
  <BottomSheet.Header>
    <Heading level={3}>Wybierz plan</Heading>
  </BottomSheet.Header>
  <BottomSheet.Body>
    <PlanList />
  </BottomSheet.Body>
</BottomSheet>

Lokalizacja Nowość

Każdy tekst renderowany przez bibliotekę, od podpowiedzi przycisków po jednostki odliczania, pochodzi z labels. Przekaż locale i tylko te etykiety, które tłumaczysz. Pozostałe zostają po angielsku. Ikony i chevron wstecz odbijają się w układach od prawej do lewej.

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

Changelog

1. v2.0.0

   2026-10-29

   Stabilna

   Wydanie poprawiające dostępność, konfigurację i odporność

   • Dodano

     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

   Stabilna

   • Naprawiono

     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.

Zobacz pełny changelog →