Skip to content

Latest commit

 

History

History
618 lines (442 loc) · 18.2 KB

4.x-5.0.0-migration.md

File metadata and controls

618 lines (442 loc) · 18.2 KB

4.x - 5.0.0 UI Kitten Migration

UI Kitten v5.0 is a significant improvement and rework of the previous version. We believe these changes bring UI Kitten to the new level of quality and feature richness. To achieve this and allow UI Kitten to grow faster and better, we had to refactor a lot of internal implementations, as well as public APIs.

We hope that next UI Kitten versions won't receive such significant upgrades and the amount of breaking changes will be kept as low as possible.

Migration Purposes

  • Flexible styling with new convenient and unified component interfaces;
  • Declarative way of rendering nested components;
  • Better typescript support;
  • Better documentation with detailed description for component examples and properties.

Understanding new API

To slightly simplify the migration process we strongly recommend getting familiar with the short list of rules we followed during the refactoring process:

  1. All components that previously could render a text by passing a string to a corresponding property now may accept a string, number, or a function component. If the function is passed, it will be called with style properties provided by Eva. This makes {componentName}Style properties redundant.

  2. In order to follow the rule above, CheckBox, Radio and Toggle components now accept the text as a child element.

  3. Icon properties are renamed to accessoryLeft and accessoryRight. (Except tabs, because it may have only one icon).

  4. Popover and related components (Tooltip and OverflowMenu) now accept its content as a child element. A component relative to which the content is rendered is now passed to anchor property.

Migration Steps

The following migration steps are required to update:

  • Update @ui-kitten/* packages to version 5 required
  • Update @eva-design/* packages to version 2 required

Update UI Kitten

npm i @ui-kitten/components @eva-design/eva@latest

// Using Yarn?
yarn add @ui-kitten/components@latest @eva-design/eva@latest

Additionally, if you use any other UI Kitten packages, you can add them like this:

npm i @ui-kitten/eva-icons@latest

// Using Yarn?
yarn add @ui-kitten/eva-icons@latest

Migrate Components

Button

Button does not accept textStyle property anymore. Instead, if having custom styles is required, function component with additional text style should be used as a child element.

import { Button, Text } from '@ui-kitten/components';

<Button>
  {evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>BUTTON</Text>}
</Button>

Icons within Button now are rendered with accessoryLeft or accessoryRight properties, replacing the old icon property.

import { Button, Icon } from '@ui-kitten/components';

const StarIcon = (evaProps) => (
  <Icon {...evaProps} name='star' />
);

<Button accessoryRight={StarIcon} />

Radio

Radio does not accept text property anymore. It was moved to children in favor of using a declarative way of building components.

import { Radio } from '@ui-kitten/components';

<Radio>Place your Text</Radio>

Also, textStyle property is no longer supported. Instead, a function component with additional text style should be used as a child element.

import { Radio, Text } from '@ui-kitten/components';

<Radio>
  {evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Text</Text>}
</Radio>

CheckBox

CheckBox does not accept text property anymore. It was moved to children in favor of using a declarative way of building components.

import { CheckBox } from '@ui-kitten/components';

<CheckBox>Place your Text</CheckBox>

Also, textStyle property is no longer supported. Instead, if having custom styles is required, function component with additional text style should be used as a child element.

import { CheckBox, Text } from '@ui-kitten/components';

<CheckBox>
  {evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Text</Text>}
</CheckBox>

Toggle

Toggle does not accept text property anymore. It was moved to children in favor of using a declarative way of building components.

import { Toggle } from '@ui-kitten/components';

<Toggle>Place your Text</Toggle>

Also, textStyle property is no longer supported. Instead, the function component with additional text style should be used as a child element.

import { Toggle, Text } from '@ui-kitten/components';

<Toggle>
  {evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Text</Text>}
</Toggle>

Input

Input has no icon property anymore. Instead, accessoryRight or accessoryLeft properties should be used.

import { Input, Icon } from '@ui-kitten/components';

const StarIcon = (evaProps) => (
  <Icon {...evaProps} name='star' />
);

<Input accessoryRight={StarIcon} />

Also, labelStyle and captionStyle properties are no longer supported. Instead, if having custom styles is required, function component with additional text style should be passed to the corresponding property.

import { Input, Text } from '@ui-kitten/components';

<Input 
  label={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Label</Text>}
  caption={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Label</Text>}
/>

Datepicker and RangeDatepicker

Datepicker has no icon property anymore. Instead, accessoryRight or accessoryLeft properties should be used.

import { Datepicker, Icon } from '@ui-kitten/components';

const StarIcon = (evaProps) => (
  <Icon {...evaProps} name='star' />
);

<Datepicker accessoryRight={StarIcon} />

Also, labelStyle and captionStyle properties are no longer supported. Instead, if having custom styles is required, function component with additional text style should be passed to the corresponding property.

import { Datepicker, Text } from '@ui-kitten/components';

<Datepicker 
  label={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Label</Text>}
  caption={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Label</Text>}
/>

Select

Select now exports two related components - SelectItem and SelectGroup, which makes it possible to accept any type of data not requiring you to have text properties for its items. Now its contents are fully controlled by you as a developer and should be passed as child elements.

import { Select, SelectItem } from '@ui-kitten/components';

<Select>
  <SelectItem title='Option 1' />
  <SelectGroup title='Group 2'>
    <SelectItem title='Option 1.1' />
    <SelectItem title='Option 1.2' />
  </SelectGroup>
</Select>

Also, labelStyle, captionStyle and placeholderStyle properties are no longer supported. Instead, if having custom styles is required, function component with additional text style should be passed to the corresponding property.

import { Select, Text } from '@ui-kitten/components';

<Select 
  label={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Label</Text>}
  caption={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Label</Text>}
  placeholder={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Placeholder</Text>}
/>

Icons within Select now are rendered with accessoryLeft or accessoryRight properties, replacing the old icon property.

import { Select, Icon } from '@ui-kitten/components';

const StarIcon = (evaProps) => (
  <Icon {...evaProps} name='star' />
);

<Select accessoryRight={StarIcon} />

We also strongly recommend visiting Select Overview page to become familiar with its API since its selection functionality was completely reworked.

Autocomplete

Autocomplete now exports a related component - AutocompleteItem, which makes it possible to accept any type of data not requiring you to have title properties for its items. Now its contents are fully controlled by you as a developer and should be passed as child elements.

For this reason, it removes renderItem and placeholderData properties in favor of children.

import { Autocomplete, AutocompleteItem } from '@ui-kitten/components';

<Autocomplete>
  <AutocompleteItem title='Option 1' />
  <AutocompleteItem title='Option 2' />
  <AutocompleteItem title='Option 3' />
</Autocomplete>

Also, labelStyle and captionStyle properties are no longer supported. Instead, if having custom styles is required, function component with additional text style should be passed to corresponding property.

import { Autocomplete, Text } from '@ui-kitten/components';

<Autocomplete 
  label={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Label</Text>}
  caption={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Label</Text>}
/>

Icons within Autocomplete now are rendered with accessoryLeft or accessoryRight properties, replacing the old icon property.

import { Autocomplete, Icon } from '@ui-kitten/components';

const StarIcon = (evaProps) => (
  <Icon {...evaProps} name='star' />
);

<Autocomplete accessoryRight={StarIcon} />

Bottom Navigation and Tabs

Tabs do not accept titleStyle property anymore. Instead, if having custom styles is required, function component with additional text style should be passed to title property.

import { BottomNavigationTab, Text } from '@ui-kitten/components';

<BottomNavigation>
  <BottomNavigationTab title={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Tab 1</Text>}/>
  <BottomNavigationTab title={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Tab 2</Text>}/>
</BottomNavigation>

TabBar and Tabs

Tabs do not accept titleStyle property anymore. Instead, if having custom styles is required, function component with additional text style should be passed to title property.

import { TabBar, Tab, Text } from '@ui-kitten/components';

<TabBar>
  <Tab title={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Tab 1</Text>}/>
  <Tab title={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Tab 2</Text>}/>
</TabBar>

TopNavigation and Actions

TopNavigation title and description properties now may accept any component instead of only strings. This made us remove titleStyle and subtitleStyle properties. Instead, the function component with additional text style should be used as a child element.

import { TopNavigation, Text } from '@ui-kitten/components';

<TopNavigation
  title={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Title</Text>}
  subtitle={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Subtitle</Text>}
/>

To support consistency with other components, Actions within TopNavigation now are rendered with accessoryLeft and accessoryRight properties, replacing old leftControl and rightControls.

import { TopNavigation, TopNavigationAction, Icon } from '@ui-kitten/components';

const BackIcon = (evaProps) => (
  <Icon {...evaProps} name='arrow-ios-back' />
);

const SettingsIcon = (evaProps) => (
  <Icon {...evaProps} name='settings' />
);

const BackAction = () => (
  <TopNavigationAction icon={BackIcon} />
);

const SettingsAction = () => (
  <TopNavigationAction icon={SettingsIcon} />
);

<TopNavigation 
  accessoryLeft={BackAction}
  accessoryRight={SettingsAction}
/>

Multiple actions can be rendered by combining them in React.Fragment.

Drawer

Drawer now exports two related components - DrawerItem and DrawerGroup, which makes it possible to accept any type of data not requiring you to have title properties for its items. Now its contents are fully controlled by you as a developer and should be passed as child elements.

import { Drawer, DrawerItem, DrawerGroup } from '@ui-kitten/components';

<Drawer>
  <DrawerItem title='Option 1'/>
  <DrawerGroup title='Group'>
    <DrawerItem title='Option 1.1'/>
    <DrawerItem title='Option 1.2'/>
  </DrawerGroup>
</Drawer>

Also, it does not export DrawerHeaderFooter component anymore as we find it useless. Instead, header and footer properties accept styles provided by Eva that should be used as the style of the container for Header of Footer of Cards.

import { Drawer, Layout, Text } from '@ui-kitten/components';

const Header = (evaProps) => (
  <Layout {...evaProps} level='2'/>
);

const Footer = (evaProps) => (
  <Layout {...evaProps}>
    <Text category='c2'>Footer</Text>
  </Layout>
);


<Drawer header={Header} footer={Footer}/>

We also strongly recommend visiting Drawer Overview page to become familiar with its API since its selection functionality was completely reworked.

Menu

Menu now exports two related components - MenuItem and MenuGroup, which makes it possible to accept any type of data not requiring you to have title properties for its items. Now its contents are fully controlled by you as a developer and should be passed as child elements.

import { Menu, MenuItem, MenuGroup } from '@ui-kitten/components';

<Menu>
  <MenuItem title='Option 1'/>
  <MenuGroup title='Group'>
    <MenuItem title='Option 1.1'/>
    <MenuItem title='Option 1.2'/>
  </MenuGroup>
</Menu>

We also strongly recommend visiting Menu Overview page to become familiar with its API since its selection functionality was completely reworked.

Popover

Popover now accept its content as child element. A component relative to which the content is rendered is now passed to anchor property.

import { Popover, Layout, Text, Button } from '@ui-kitten/components';

const renderToggleButton = () => (
  <Button>TOGGLE POPOVER</Button>
);

<Popover anchor={renderToggleButton}>
  <Layout>
    <Text>Welcome to UI Kitten</Text>
  </Layout>
</Popover>

Tooltip

Tooltip now accept its text as child element. A component relative to which the content is rendered is now passed to anchor property.

import { Tooltip, Button } from '@ui-kitten/components';

const renderToggleButton = () => (
  <Button>TOGGLE TOOLTIP</Button>
);

<Tooltip anchor={renderToggleButton}>
  Welcome to UI Kitten
</Tooltip>

Overflow Menu

OverflowMenu data property is replaced in favor to child elements, which makes it possible to accept any type of data not requiring you to have title properties for its items. Now its contents are fully controlled by you as a developer and should be passed as child elements.

A component relative to which the menu is rendered is now passed to anchor property.

import { OverflowMenu, MenuItem, Button } from '@ui-kitten/components';

const renderToggleButton = () => (
  <Button>TOGGLE MENU</Button>
);

<OverflowMenu anchor={renderToggleButton}>
  <MenuItem title='Option 1' />
  <MenuItem title='Option 2' />
  <MenuItem title='Option 3' />
</OverflowMenu>

We also strongly recommend visiting OverflowMenu Overview page to become familiar with its API since its selection functionality was completely reworked.

List and Items

ListItem now calls onPress without its index. We were motivated to remove this in favor of having better performance when rendering large lists.

Also, titleStyle and descriptionStyle properties are no longer supported. Instead, if having custom styles is required, function component with additional text style should be passed to the corresponding property.

import { ListItem, Text } from '@ui-kitten/components';

<ListItem 
  title={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Title</Text>}
  description={evaProps => <Text {...evaProps} style={[evaProps.style, myStyle]}>Description</Text>}
/>

Icons within List Items now are rendered with accessoryLeft or accessoryRight properties, replacing old icon and accessory properties.

import { ListItem, Icon } from '@ui-kitten/components';

const StarIcon = (evaProps) => (
  <Icon {...evaProps} name='star' />
);

<ListItem accessoryRight={StarIcon} />

Card

Card does not export CardHeader component anymore as we find it useless. Instead, header and footer properties accept styles provided by Eva that should be used as the style of the container for Header of Footer of Cards.

import { Card, Layout, Text } from '@ui-kitten/components';

const Header = (evaProps) => (
  <Layout {...evaProps}>
    <Text category='h6'>Title</Text>
    <Text category='s1'>Description</Text>
  </Layout>
);

const Footer = (evaProps) => (
  <Layout {...evaProps}>
    <Text category='c2'>Footer</Text>
  </Layout>
);


<Card header={Header} footer={Footer}/>

Migrate High Order Components

For components wrapped in UI Kitten High Order Functions, we combined properties it injects into a single one for having better control on it and reduce the number of compiler warnings when an unexpected property is passed to an unexpected component.

withStyles

Now injects a single eva property, which combines theme and style.

import { View } from 'react-native';
import { withStyles } from '@ui-kitten/components';

const MyComponent = (props) => (
  <View style={props.eva.style.container}/>
);

export const MyStyledComponent = withStyles(MyComponent, theme => ({
  container: {
    backgroundColor: theme['color-primary-default'],
  },
}));

styled

Now injects a single eva property, which combines dispatch function, theme and style properties.

import React from 'react';
import { View } from 'react-native';
import { styled } from '@ui-kitten/components';

class MyComponent extends React.Component {
  static styledComponentName = 'MyComponent';

  render() {
    const { eva, ...restProps } = this.props;
    return (
      <View />
    );
  }
}

export const MyStyledComponent = styled(MyComponent);