axp-base to dls-react Migration Guide

Summary

In February 2020 we released version 1.0.0 of DLS React, which is built off DLS version 6.

Dependencies

axp-base is on DLS version 5 while dls-react is on DLS version 6. dls-react has built in CSS obj styling with Emotion, but will still need a DLS stylesheet for global styling.

Use DLS version 6. If you cannot upgrade to version 6, use DLS Mini or <DefaultStyle /> from dls-react.

DLS Mini includes all the global element styling that will allow axp-base and dls-react components live together on the same page. <DefaultStyle /> is a helmet component that will peek at the stylesheet in the page head and inject DLS Mini if there is no version 6+ DLS stylesheet.

Imports

Replace the axp-base imports with @americanexpress/dls-react.

Accordion

Major Differences

• The Accordion component from axp-base is named Collapsible in DLS React, which also has CollapsibleContent, CollapsibleHeading, and CollapsiblePanel sub-components.

• axp-base uses a single component and props for the icon. dls-react icon is built in and handled by CollapsiblePanel.

Migration Recipe

1. Rename Accordion to Collapsible and remove props.
2. Replace Accordion contents with CollapsibleContent, CollapsibleHeading, or CollapsiblePanel components.
3. Replace the label prop with labelledBy referencing the appropriate id.

Examples

axp-base

1/* eslint-disable semi */
2<Accordion>
3  <Collapsible label="some label" privateKey="item1Key">
4    <p>Content 1</p>
5  </Collapsible>
6  <Collapsible label="some other label" privateKey="item2Key">
7    <p>Content 1</p>
8  </Collapsible>
9</Accordion>;

DLS React

1<Collapsible>
2  <CollapsiblePanel id="collapsible-p-h1" icon={<IconHotel />}>
3    Hotel
4  </CollapsiblePanel>
5  <CollapsibleContent labelledBy="collapsible-p-h1">
6    <p className="pad">Content 1</p>
7  </CollapsibleContent>
8  <CollapsiblePanel id="collapsible-p-h2" icon={<IconAirplane />}>
9    Air
10  </CollapsiblePanel>
11  <CollapsibleContent labelledBy="collapsible-p-h2">
12    <p className="pad">Content 2</p>
13  </CollapsibleContent>
14  <CollapsiblePanel id="collapsible-p-h3" icon={<IconCar />}>
15    Car
16  </CollapsiblePanel>
17  <CollapsibleContent labelledBy="collapsible-p-h3">
18    <p className="pad">Content 3</p>
19  </CollapsibleContent>
20</Collapsible>;

Alert

Major Differences

• The Alert component from axp-base is named PageLevelMessage in DLS React. The Alert component in DLS React is meant for use with form inputs.
• PageLevelMessage hides itself when the close button is clicked. Alert in axp-base requires manually hiding the component.

Migration Recipe

1. Rename Alert to PageLevelMessage.
2. Change the type prop. “positive” becomes “success” and “negative” becomes “failure”.
3. Remove the icon prop unless you are using a custom icon.
4. Remove any show/hide logic tied to the onClose prop.
5. If you do not want a close button, set the dismissible prop to false.
6. Remove the closeTitle prop.
7. Rename the onClose prop to onDismiss.

Examples

axp-base

1<Alert type="positive" label="Alert Message" icon="dls-icon-success-filled" onClose={closeHandler} />;

DLS React

1<PageLevelMessage type="success" onDismiss={closeHandler}>
2  Alert Message
3</PageLevelMessage>;

AmexLogoBlueBox

Major Differences

• The AmexLogoBlueBox component in axp-base uses the size of the containing div, while the DLS React Logo component takes an explicit size prop.
• The DLS React Logo component does not support arbitrary colors.

Migration Recipe

1. Rename AmexLogoBlueBox to Logo.
2. Set the styleType prop to "bluebox-solid".
3. Set the size prop to the appropriate value for the design.

Examples

axp-base

1<div>
2  <AmexLogoBlueBox />
3</div>;

DLS React

1<Logo styleType="bluebox-solid" size="lg" />;

AmexLogoHorizontal

Major Differences

• The DLS React horizontal logo uses the current branding.
• The AmexLogoHorizontal component in axp-base uses the size of the containing div, while the DLS React Logo component takes an explicit size prop.
• The DLS React Logo component does not support arbitrary colors.

Migration Recipe

1. Rename AmexLogoHorizontal to Logo.
2. Set the styleType prop to “line”.
3. Set the size prop to the appropriate value for the design.

Examples

axp-base

1<div>
2  <AmexLogoHorizontal />
3</div>;

DLS React

1<Logo styleType="bluebox-solid" size="lg" />;

Anchor

Major Differences

• The DLS React Anchor component is named Anchor.
• The label prop in axp-base is children in dls-react.

Migration Recipe

1. Replace the Analytics(Anchor) component with name Anchor.
2. Rewrite the label prop as children within the Anchor.

Examples

axp-base

1<Anchor label="Anchor Label" href="http://www.americanexpress.com" />;

DLS React

1<Anchor href="http://www.americanexpress.com">Anchor Label</Anchor>;

Badge

Major Differences

• The DLS React badge color is set by the theme prop rather than the type prop.
• There is no DLS React equivalent of the parsed badge.

Migration Recipe

1. Convert the type prop to the value for the desired badge style.
2. Add a theme prop if needed for coloring.
3. Add a function if needed to parse the text for a badge.

Examples

axp-base

1<Badge text="Success" type="success" />;

DLS React

1<Badge type="text" theme={dlsColorWarningBg}>
2  Success
3</Badge>;

axp-base

1<Badge text="All" type="pill" />;

DLS React

1<Badge type="outline">All</Badge>;

BarProgress

Major Differences

• The component in dls-react is named SegmentedLinearTracker.
• The steps are children components called SegmentedLinearTrackerStep, not props.

Migration Recipe

1. Rename the component to SegmentedLinearTracker.
2. Create SegmentedLinearTrackerStep components for each step and add them as children inside SegmentedLinearTracker.
3. currentStep is the same logic handled by SegmentedLinearTracker.

Examples

axp-base

1<BarProgress
2  steps={[
3    'Step 1',
4    'Step 2',
5    'Step 3',
6  ]}
7  currentStep={2}
8/>;

DLS React

1<SegmentedLinearTracker currentStep={2}>
2  <SegmentedLinearTrackerStep label="Step 1" />
3  <SegmentedLinearTrackerStep label="Step 2" />
4  <SegmentedLinearTrackerStep label="Step 3" />
5</SegmentedLinearTracker>;

Breadcrumbs

Major Differences

• The DLS React component is named BreadcrumbTrail.
• DLS React uses child components for the breadcrumb trail, rather than a crumbs prop.

Migration Recipe

1. Rename the Breadcrumbs tag to BreadcrumbTrail.
2. Replace the crumbs prop with Breadcrumb component children.

Examples

axp-base

1<Breadcrumbs
2  crumbs={[
3    { content: 'Link 1', url: '#example1' },
4    { content: 'Link 2', url: '#example2' },
5    { content: 'Link 3' },
6  ]}
7/>;

DLS React

1<BreadcrumbTrail>
2  <Breadcrumb href="#example1">Link 1</Breadcrumb>
3  <Breadcrumb href="#example2">Link 2</Breadcrumb>
4  <Breadcrumb>Link 3</Breadcrumb>
5</BreadcrumbTrail>;

Button

Major Differences

• axp-base uses classes to style buttons. DLS React uses the styleType prop instead.
• There is no label prop in DLS React so labels must be added as children.

Migration Recipe

1. Replace the className prop with the appropriate styleType prop.
2. Move the label prop value inside the Button as a child.
3. Rename the working prop to isLoading.

Examples

axp-base

1<Button className="btn-block margin-auto-lr btn-primary" working={true}>
2  Button text
3</Button>;

DLS React

1<Button styleType="primary" isLoading={true}>
2  Button text
3</Button>;

axp-base

1<Button className="btn-block margin-auto-lr btn-secondary" label="Button text" />;

DLS React

1<Button styleType="secondary">Button text</Button>;

Checkbox

Major Differences

• The onChange prop for Checkbox in axp-base receives a boolean value with the checked state. In DLS React, it receives the entire event, and the checked state is available as event.target.checked.

Migration Recipe

1. Rewrite any onChange handlers for your checkbox to use the target.checked value from the event.

Examples

axp-base:

1toggle = (checked) => {
2  this.setState({ isChecked: checked });
3};

DLS React:

1toggle = (event) => {
2  this.setState({ isChecked: event.target.checked });
3};

Collapsible

Major Differences

• The DLS React Collapsible component uses the id to connect the panel to the content it expands, while axp-base uses a parent-child relationship.
• The panel and content are separate components within the Collapsible wrapper.

Migration Recipe

1. Convert the label prop to a CollapsiblePanel component.
2. Wrap the collapsible content in a CollapsibleContent component.
3. Add an id prop to the CollapsiblePanel and a matching labelledBy prop to the CollapsibleContent.

Examples

axp-base:

1<Collapsible label="Collapsible Header">
2  <div>Collapsible Content</div>
3</Collapsible>;

DLS React:

1<Collapsible>
2  <CollapsiblePanel id="collapsible-id">
3    Collapsible Header
4  </CollapsiblePanel>
5  <CollapsibleContent labelledBy="collapsible-id">
6    <div>Collapsible Content</div>
7  </CollapsibleContent>
8</Collapsible>;

CurrencyInput

Major Differences

• axp-base prop decimalDigits is showFractions in dls-react.

Migration Recipe

Defaults are the same, so no major changes necessary

Examples

axp-base:

1<CurrencyInput />;

DLS React:

1<CurrencyInput />;

Dropdown

Major Differences

• The Dropdown component in axp-base is named Select in dls-react

• The Select component in DLS React uses children for the options, while axp-base uses an options prop.

• DLS React uses separate Label and Alert components, rather than props.

Migration Recipe

1. Replace the options prop with SelectOption children.
2. Move the label prop to a separate Label component before the Select.
3. Move the warning prop to a separate Alert component after the Select.
4. Update the logic that was used for warning to set the status prop on the Select to “default”, “error”, or “success”.
5. If it’s a controlled dropdown: a. Rewrite the onChange method to use a signature of (event) rather than (value, event). The value can be found at event.target.value.

Examples

axp-base:

1<Dropdown
2  label="Select a size"
3  id="size"
4  value={size}
5  options={[
6    { value: '', id: '', label: 'Select' },
7    { value: 'sm', id: 'sm', label: 'Small' },
8    { value: 'md', id: 'md', label: 'Medium' },
9    { value: 'lg', id: 'lg', label: 'Large' },
10  ]}
11  onChange={(value, event) => setSize(value.value, event)}
12  warning={!valid && <span>Invalid size</span>}
13/>;

DLS React:

1<Fragment>
2  <Label htmlFor="size">
3    Select a size
4  </Label>
5  <Select
6    id="size"
7    value={size}
8    onChange={(event) => setSize(event.value.target, event)}
9    status={!valid ? 'error' : 'default'}
10  >
11    <SelectOption value="">Select</SelectOption>
12    <SelectOption value="sm">Small</SelectOption>
13    <SelectOption value="md">Medium</SelectOption>
14    <SelectOption value="lg">Large</SelectOption>
15  </Select>
16  {!valid && <Alert>Invalid size</Alert>}
17</Fragment>;

FlagSelector

Major Differences

• The DLS React Flag supports multiple sizes using the size prop. The default size is "sm" and the axp-base component corresponds to “lg”.

Migration Recipe

1. Rename FlagSelector to Flag.
2. Add the appropriate size prop.

Examples

axp-base

1<FlagSelector countryCode="US" />;

DLS React

1<Flag countryCode="US" size="lg" />;

Icon

Major Differences

• DLS React has separate components for each DLS icon, while axp-base uses CSS classes to specify the icon.
• DLS React uses SVG elements for icons, while axp-base uses a custom icon font.

Migration Recipe

1. Replace the generic Icon component with the appropriate specific icon component.

Examples

axp-base

1<Icon className="dls-icon-alert" />;

DLS React

1<IconAlert />;

Input

Major Differences

• The Input component in DLS React uses separate Label and Alert components, rather than props.

Migration Recipe

1. Move the label prop to a separate Label component before the Input.
2. Move the warning prop to a separate Alert component after the Input.
3. Update the logic that was used for warning to set the status prop on the Input and Label to “default”, “success”, or “error”.
4. If it’s a controlled input: a. Rewrite the onChange method to use a signature of (event) rather than (value, event). The value can be found at event.target.value. b. Rewrite the onBlur method to use a signature of (event) rather than (value, event).

Examples

axp-base:

1<Input
2  label="Input label"
3  id="example-input"
4  value={value}
5  onChange={(value) => setValue(value)}
6  onBlur={(value) => checkValidity(value)}
7  warning={!valid && <span>Invalid value</span>}
8/>;

DLS React:

1<Fragment>
2  <Label htmlFor="example-input">
3    Input label
4  </Label>
5  <Input
6    id="example-input"
7    value={value}
8    onChange={(event) => setValue(event.target.value)}
9    onBlur={(event) => checkValidity(event.target.value)}
10    status={!valid ? 'error' : 'default'}
11  />
12  {!valid && <Alert>Invalid value</Alert>}
13</Fragment>;

Loader

Major Differences

• The default circle Loader in axp-base is named ProgressCircle in DLS React.

Migration Recipe

1. Rename Loader to ProgressCircle.

Examples

axp-base:

1if (isLoading()) {
2  return <Loader />;
3}
4return <Component />;

DLS React:

1if (isLoading()) {
2  return <ProgressCircle />;
3}
4return <Component />;

Modal

Major Differences

• The axp-base Modal is shown or hidden using the shown prop. The DLS React Modal is shown or hidden like any other React component that is conditionally displayed.
• DLS React also contains helper components to make it easier to style modals according to the DLS.

Migration Recipe

1. Replace the shown prop with logic to hide or show the modal.
2. Replace the title bar JSX with ModalHeader.
3. Replace the body JSX with ModalBody.
4. Replace the footer JSX with ModalFooter.

Examples

axp-base:

1<Modal shown={isShown}>Modal content</Modal>;

DLS React:

1isShown && <Modal>Modal content</Modal>;

axp-base:

1<div className="modal-header dls-bright-blue-bg dls-white">
2  <h2 className="fluid text-align-center heading-3">Modal Title</h2>
3  <Button
4    id="closeModalButton"
5    onClick={this.hideModal}
6    className="btn-inline dls-glyph-close pad-0"
7  />
8</div>;

DLS React:

1<ModalHeader onCloseClick={this.hideModal}>
2  <h2 className="fluid heading-3">Modal Title</h2>
3</ModalHeader>;

RadioGroup

Major Differences

• The Radio component in axp-base is named RadioButton in DLS React.
• The onChange prop in axp-base receives the value directly. In DLS React, it receives the entire event, and the value is available as event.target.value.

Migration Recipe

1. Rename Radio to RadioButton.
2. Rename the selectedValue prop to checked.
3. Rewrite any onChange handlers to use the target.value from the event.

Examples

axp-base

1<RadioGroup selectedValue={value} onChange={setValue} name="test">
2  <Radio id="radio-1" label="Choice A" value="A" />
3  <Radio id="radio-2" label="Choice B" value="B" />
4</RadioGroup>;

DLS React

1<RadioGroup checked={value} onChange={(event) => setValue(event.target.value)}>
2  <Legend>Pick a choice:</Legend>
3  <RadioButton id="radio-3" label="Choice A" value="A" />
4  <RadioButton id="radio-4" label="Choice B" value="B" />
5</RadioGroup>;

StepProgress

Major Differences

• The component is named MultiStepTracker in dls-react and has significant visual differences.
• Instead of steps props, dls-react has Step components as children within MultiStepTracker.

Migration Recipe

1. RenameStepProgress toMultiStepTracker.
2. Remove the steps props and create Step components for each step as children within MultiStepTracker.

Examples

axp-base:

1<StepProgress
2  steps={[
3    'Step 1',
4    'Step 2',
5    'Step 3',
6  ]}
7  currentStep={2}
8/>;

DLS React:

1<MultiStepTracker currentStep={2}>
2  <Step label="Step 1" />
3  <Step label="Step 2" />
4  <Step label="Step 3" />
5</MultiStepTracker>;

Tabs

Major Differences

• The tab sub-components have different names in DLS React.
• The selected tabs are tracked by id in DLS React and by numeric index in axp-base.

Migration Recipe

1. Rename the components:

• Tabs is now TabGroup
• TabList is now TabMenu
• TabPanels is now TabContentGroup
• TabPanel is now TabContent

2. Add an id prop to every Tab.
3. Add that id to the corresponding TabContent component as the labelledBy prop.
4. Remove any mobileLabel props.
5. Remove className="fluid" if present.
6. If it’s a controlled set of tabs:
7. Rename the TabGroup onSelect prop to onChange.
8. Rename the TabGroup selectedIndex prop to selectedTab.
9. Rewrite your change handler. Instead of getting an index passed to your function, you will get the event and the tab id.

Examples

axp-base:

1<Tabs onSelect={(selectedIndex) => selectTab(selectedIndex)} selectedIndex={selectedIndex}>
2  <TabList>
3    <Tab>Tab 1</Tab>
4    <Tab>Tab 2</Tab>
5  </TabList>
6  <TabPanels>
7    <TabPanel>Tab 1 content</TabPanel>
8    <TabPanel>Tab 2 content</TabPanel>
9  </TabPanels>
10</Tabs>;

DLS React:

1<TabGroup onChange={(event, id) => selectTab(id)} selectedTab={selectedTab}>
2  <TabMenu>
3    <Tab id="tab-1">Tab 1</Tab>
4    <Tab id="tab-2">Tab 2</Tab>
5  </TabMenu>
6  <TabContentGroup>
7    <TabContent labelledBy="tab-1"> Tab 1 content</TabContent>
8    <TabContent labelledBy="tab-2"> Tab 2 content</TabContent>
9  </TabContentGroup>
10</TabGroup>;

TextArea

Major Differences

• The Textarea component in DLS React uses separate Label and Alert components, rather than props.

Migration Recipe

1. Rename TextArea to Textarea
2. Move the label prop to a separate Label component before the Textarea.
3. Move the warning prop to a separate Alert component after the Textarea.
4. Update the logic that was used for warning to set the status prop on the Textarea and Label to “default”, “error”, or “success”.

Examples

axp-base:

1<TextArea
2  label="Text area label"
3  id="example-textarea"
4  value={value}
5  warning={!valid && <span>Invalid value</span>}
6/>;

DLS React:

1<Fragment>
2  <Label htmlFor="example-textarea" valid={valid}>
3    Text area label
4  </Label>
5  <Textarea id="example-textarea" value={value} valid={valid} />
6  {!valid && <Alert>Invalid value</Alert>}
7</Fragment>;

Tooltip

Major Differences

• The Tooltip component in dls-react uses separate Tooltip and TooltipButton components.
• There is no need to define tooltipBox or toggleBox positioning since it is handled out of the box in dls-react.

Migration Recipe

1. Rename Analytics(Tooltip) to Tooltip
2. Rename the position prop to placement.
3. Add a triggerElement.
4. Remove className="tooltip-content" since it’s already styled by dls-react.

Examples

axp-base:

1<AnalyticsTooltip
2  className="test-class"
3  label="tooltip label"
4  position="bottom"
5  contentId="myTooltipContent"
6  tooltipBox={{
7    left: 10,
8    right: 190,
9    bottom: 90,
10  }}
11  toggleBox={{
12    left: 150,
13    right: 170,
14    bottom: 20,
15  }}
16>
17  <span className="tooltip-content">
18    Charles Frost
19  </span>
20</AnalyticsTooltip>;

DLS React:

1<Tooltip
2  id="tooltip-info-top"
3  triggerElement={(
4    <TooltipButton info={true} active={true} icon={<GlyphInfo />} />
5  )}
6  placement="top"
7  info={true}
8  open={true}
9>
10  Charles Frost
11</Tooltip>;

References

axp-base repo

axp-base docs

dls-react repo

dls-react docs

If you have any more questions about the migration or on DLS in general, please ask in the dls-tech channel in Slack.