UI Kitten components are styled using Eva Design System configuration files called mappings. By customizing these mappings, you can modify the appearance and behavior of built-in components without changing their source code.
What is a Mapping? A mapping is a JSON or JavaScript object that describes the styling rules and behavior for each UI Kitten component. These mappings are processed by the Eva Design System to generate the final styles applied to components.
Working with mappings provides extensive flexibility but requires understanding the Eva Design System structure. This guide covers common customization scenarios.
Types of Changes You can make two types of changes to component mappings:
Single Parameter Change individual style properties like backgroundColor, fontSize, or borderRadius.
Semantic Property Modify entire property groups like appearances, variants, or default values.
Changing a Single Parameter
Create a Mapping File
Create mapping.json in your project root: { "components" : { "Button" : { "meta" : {}, "appearances" : {} } } }
Find the Parameter Location
First, identify where the parameter is declared. Look at the default mapping in node_modules/@eva-design/eva/mapping.json. Check the meta section for default appearance and variants: { "components" : { "Button" : { "meta" : { "appearances" : { "filled" : { "default" : true } }, "variantGroups" : { "status" : { "primary" : { "default" : true } } } } } } }
Locate the Style Definition
Navigate to the default appearance configuration: { "appearances" : { "filled" : { "mapping" : {}, "variantGroups" : { "status" : { "primary" : { "backgroundColor" : "color-primary-default" } } } } } }
Override in Your Mapping
Update your mapping.json to override the parameter: { "components" : { "Button" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : {}, "variantGroups" : { "status" : { "primary" : { "backgroundColor" : "#FF6B35" } } } } } } } }
Apply the Mapping
Pass your custom mapping to ApplicationProvider: import React from 'react' ; import * as eva from '@eva-design/eva' ; import { ApplicationProvider } from '@ui-kitten/components' ; import customMapping from './mapping.json' ; export default () => ( < ApplicationProvider { ... eva } customMapping = { customMapping } theme = { eva . light } > { /* Your app */ } </ ApplicationProvider > ) ;
If you’re using @ui-kitten/metro-config, custom mappings are applied automatically. Check your metro.config.js file.
Complete Example: Custom Button Color Let’s change the default Button background color to pink:
{ "components" : { "Button" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : {}, "variantGroups" : { "status" : { "primary" : { "backgroundColor" : "pink" , "borderColor" : "pink" } } } } } } } }
Changing Multiple Parameters You can override multiple properties at once:
{ "components" : { "Button" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : {}, "variantGroups" : { "status" : { "primary" : { "backgroundColor" : "#FF6B35" , "borderColor" : "#FF6B35" , "textColor" : "#FFFFFF" , "paddingVertical" : 16 , "paddingHorizontal" : 24 , "borderRadius" : 8 } } } } } } } }
Customizing Multiple Components { "components" : { "Button" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : {}, "variantGroups" : { "status" : { "primary" : { "backgroundColor" : "#FF6B35" } } } } } }, "Input" : { "meta" : {}, "appearances" : { "default" : { "mapping" : { "borderColor" : "#FF6B35" , "borderRadius" : 8 } } } }, "Card" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : { "borderRadius" : 16 , "paddingVertical" : 24 , "paddingHorizontal" : 24 } } } } } }
Changing Semantic Properties Change Default Appearance Make the outline appearance default for buttons:
{ "components" : { "Button" : { "meta" : { "appearances" : { "outline" : { "default" : true } } } } } }
Now buttons render as outline by default:
< Button > Outline by default </ Button > < Button appearance = 'filled' > Explicitly filled </ Button >
Change Default Variant Make the large size default:
{ "components" : { "Button" : { "meta" : { "variantGroups" : { "size" : { "large" : { "default" : true } } } } } } }
Add Custom State Styles Customize how components look in different states:
{ "components" : { "Button" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : { "backgroundColor" : "color-primary-default" , "state" : { "focused" : { "backgroundColor" : "color-primary-focus" , "borderColor" : "color-primary-focus" , "borderWidth" : 2 }, "active" : { "backgroundColor" : "color-primary-active" }, "disabled" : { "backgroundColor" : "color-primary-disabled" , "opacity" : 0.5 } } } } } } } }
Component-Specific Examples Understanding the Mapping Hierarchy The Eva Design System processes mappings in this order:
Base Appearance
Default styles from appearances.[name].mapping
Variant Groups
Styles from active variants in variantGroups
States
Styles from active states in state
Component Props
Inline styles passed via style prop
Later styles override earlier ones, so component props have the highest priority.
Using Theme Variables Instead of hardcoding values, reference theme variables:
{ "components" : { "Button" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : {}, "variantGroups" : { "status" : { "primary" : { "backgroundColor" : "color-primary-500" , "borderColor" : "color-primary-500" , "textColor" : "text-control-color" } } } } } } } }
Using theme variables ensures your components automatically adapt when users switch between light and dark themes.
Common Customization Patterns Rounded Corners Everywhere { "components" : { "Button" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : { "borderRadius" : 12 } }, "outline" : { "mapping" : { "borderRadius" : 12 } } } }, "Input" : { "meta" : {}, "appearances" : { "default" : { "mapping" : { "borderRadius" : 12 } } } }, "Card" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : { "borderRadius" : 12 } } } } } }
Increase Padding { "components" : { "Button" : { "meta" : {}, "appearances" : { "filled" : { "mapping" : { "paddingVertical" : 16 , "paddingHorizontal" : 24 } } } } } }
Custom Border Width { "components" : { "Input" : { "meta" : {}, "appearances" : { "default" : { "mapping" : { "borderWidth" : 2 } } } } } }
Best Practices
Start Small
Begin by customizing one component at a time to understand the structure.
Use Theme Variables
Reference theme variables instead of hardcoded values for consistency.
Test All Variants
After customizing, test all appearance and status combinations.
Document Changes
Keep track of which components and properties you’ve customized.
Version Control
Store your mapping.json in version control to track changes over time.
Debugging Tips If your customizations aren’t applying:
Verify the mapping is passed to ApplicationProvider
Check the JSON syntax is valid
Ensure you’re modifying the correct appearance/variant
Look for typos in parameter names
Check console for Eva Design System warnings
Next Steps
Custom Mapping Create completely custom components
Glossary Learn Eva Design System terminology
