Instala a Native-UI em menos de um minuto

1. 1

   Instala o pacote e as dependências peer

   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

   Carrega a Space Grotesk (usada pelo tema Aurora, o tema por defeito)

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

3. 3

   Envolve a tua app

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

4. 4

   Compõe ecrãs

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

Atualizar a partir da 1.x 2.0

A versão 2.0 requer React 19, React Native 0.84+ e Reanimated 4, e remove as APIs descontinuadas na 1.x. As mudanças de nome abaixo cobrem a maioria das apps. O guia lista cada alteração com o código antes e depois.

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

Ler o guia de atualização completo →

Temas

Muda entre claro, escuro ou sistema instantaneamente, ou troca todo o aspeto com uma variante de tema. A Native-UI inclui duas: Aurora (a original) e Bloom (suave, arredondada, violeta). Cada variante traz os seus próprios presets de acento, o customAccent sobrepõe uma única cor e o theme.components sobrepõe os tokens de qualquer componente. Só passas o que muda.

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

Presets de acento

Tokens de design

Cada superfície (cor, espaçamento, raio, tipografia, sombra) é um token nomeado. Os componentes apenas leem tokens, por isso alterar um token propaga-se por todo o sistema.

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

Acessibilidade

Cada componente interativo vem com valores de acessibilidade por defeito: funções, etiquetas, hit slop, anúncios para leitores de ecrã e suporte a movimento reduzido. As cores do texto são verificadas face ao contraste WCAG em todas as superfícies (minTextContrast, 4.5 por defeito, 7 para AAA). Podes sobrepor qualquer valor por instância.

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

Comportamento de plataforma

Os componentes adaptam-se à plataforma anfitriã: háptica, áreas seguras, gestão do teclado e caixas de diálogo seguem as convenções do iOS e do Android, o InputPrompt usa o prompt do sistema no iOS e os leitores de ecrã podem fechar sheets com o seu gesto de escape. Obténs correção de plataforma sem escrever código de plataforma.

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

Localização Novo

Cada texto que a biblioteca renderiza, das dicas dos botões às unidades da contagem decrescente, vem de labels. Passa um locale e apenas as labels que traduzires. As restantes ficam em inglês. Os ícones e o chevron de voltar são espelhados em layouts da direita para a esquerda.

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

Registo de alterações

1. v2.0.0

   2026-10-29

   Estável

   Versão de acessibilidade, configuração e robustez

   • Adicionado

     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

   Estável

   • Corrigido

     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.

Ver o registo completo →