IntroductionScreen #

Introduction Screen allows you to have a screen on an app's first launch to, for example, explain your app. This widget is very customizable with a great design.

introduction_screen uses another package, dots_indicator, that I also created.

Installation #

You just need to add introduction_screen as a dependency in your pubspec.yaml file.

dependencies:
  introduction_screen: ^3.1.2

Examples #

Not all of the many parameters in each class are used in these examples. See Parameter Lists for the complete documentation for each class.

Note: if you want to display IntroductionScreen only once, like on the first start of your app, use shared_preferences (or a similar strategy) to save the status of whether it has been already displayed or not. It's not responsibility of this package to handle this.

PageViewModel #

A list of PageViewModels is used for IntroductionScreen's pages parameter.

Simple page

This example only defines the title, body, and image parameters. (You can define image as any widget.)

PageViewModel(
  title: "Title of introduction page",
  body: "Welcome to the app! This is a description of how it works.",
  image: const Center(
    child: Icon(Icons.waving_hand, size: 50.0),
  ),
)

Page with custom colors

This example defines the color of the page using the decoration parameter. The image link does not exist and is only for example.

PageViewModel(
  title: "Title of blue page",
  body: "Welcome to the app! This is a description on a page with a blue background.",
  image: Center(
    child: Image.network("https://example.com/image.png", height: 175.0),
  ),
  decoration: const PageDecoration(
    pageColor: Colors.blue,
  ),
)

Page with custom text style

This example defines custom TextStyles in the decoration parameter for the title and body.

PageViewModel(
  title: "Title of orange text and bold page",
  body: "This is a description on a page with an orange title and bold, big body.",
  image: const Center(
    child: Text("👋", style: TextStyle(fontSize: 100.0)),
  ),
  decoration: const PageDecoration(
    titleTextStyle: TextStyle(color: Colors.orange),
    bodyTextStyle: TextStyle(fontWeight: FontWeight.w700, fontSize: 20.0),
  ),
)

Page with a footer (button)

This example defines a footer for the page with a button. The image does not exist and is only for example.

PageViewModel(
  title: "Title of custom button page",
  body: "This is a description on a page with a custom button below.",
  image: Image.asset("res/images/logo.png", height: 175.0),
  footer: ElevatedButton(
    onPressed: () {
      // On button pressed
    },
    child: const Text("Let's Go!"),
  ),
)

Page with widget body

This example defines the page body using bodyWidget and a Widget, rather than with body and a String. Only use body or bodyWidget. The titleWidget parameter does the same thing for the title.

PageViewModel(
  title: "Title of custom body page",
  bodyWidget: Row(
    mainAxisAlignment: MainAxisAlignment.center,
    children: const [
      Text("Click on "),
      Icon(Icons.edit),
      Text(" to edit a post"),
    ],
  ),
  image: const Center(child: Icon(Icons.android)),
)

IntroductionScreen #

The IntroductionScreen Widget is the single object that holds all pages and related navigation and settings. In these examples, listPagesViewModel is a list of pages. A page is a PageViewModel object, like the examples in the previous section.

Note:

• If you not provide the next parameter, the "Next" button will be not displayed. The parameter showNextButton must then be set to false.
• If you want to display the "Skip" button, you must add a skip parameter and set showSkipButton to true.
• The done parameter is only required if showDoneButton is true.

Simple intro screen

This example only defines the pages, showNextButton, done, and onDone parameters.

IntroductionScreen(
  pages: listPagesViewModel,
  showNextButton: false,
  done: const Text("Done"),
  onDone: () {
    // On button pressed
  },
)

Intro screen with skip button

This example defines showSkipButton and skip to show the "Skip" button on all pages except the last one.

IntroductionScreen(
  pages: listPagesViewModel,
  showSkipButton: true,
  showNextButton: false,
  skip: const Text("Skip"),
  done: const Text("Done"),
  onDone: () {
    // On button pressed
  },
)

Intro screen with back button

This example defines showBackButton and back to show the "Back" button on all pages except the first one.

IntroductionScreen(
  pages: listPagesViewModel,
  showBackButton: true,
  showNextButton: false,
  back: const Icon(Icons.arrow_back),
  done: const Text("Done"),
  onDone: () {
    // On button pressed
  },
)

Intro screen with custom button text and dots indicators

This example defines dotsDecorator to show a custom implementation of the page progress dots. This example also uses a custom style for the "Done" button, bolding it.

IntroductionScreen(
  pages: listPagesViewModel,
  showSkipButton: true,
  skip: const Icon(Icons.skip_next),
  next: const Text("Next"),
  done: const Text("Done", style: TextStyle(fontWeight: FontWeight.w700)),
  onDone: () {
    // On Done button pressed
  },
  onSkip: () {
    // On Skip button pressed
  },
  dotsDecorator: DotsDecorator(
    size: const Size.square(10.0),
    activeSize: const Size(20.0, 10.0),
    activeColor: Theme.of(context).colorScheme.secondary,
    color: Colors.black26,
    spacing: const EdgeInsets.symmetric(horizontal: 3.0),
    activeShape: RoundedRectangleBorder(
        borderRadius: BorderRadius.circular(25.0)
    ),
  ),
)

Intro screen with custom button style

A custom style will be applied to all buttons using the baseBtnStyle parameter ("Back", "Skip", "Next", "Done"). Specific button style parameters may also be used: backStyle, skipStyle, nextStyle, doneStyle.

If both baseBtnStyle and a specific button style are defined, the baseBtnStyle will be merge with specific style.

The following is the default button style:

TextButton.styleFrom(
  shape: RoundedRectangleBorder(
    borderRadius: BorderRadius.circular(8.0),
  ),
)

This example will override the default in the following ways:

• All buttons have a light grey background
• The "Skip" button is red
• The "Done" button is green
• The "Next" button is blue

IntroductionScreen(
  pages: listPagesViewModel,
  showSkipButton: true,
  skip: const Text("Skip"),
  next: const Text("Next"),
  done: const Text("Done"),
  onDone: () {
    // When done button is press
  },
  baseBtnStyle: TextButton.styleFrom(
    backgroundColor: Colors.grey.shade200,
  ),  
  skipStyle: TextButton.styleFrom(primary: Colors.red),  
  doneStyle: TextButton.styleFrom(primary: Colors.green),  
  nextStyle: TextButton.styleFrom(primary: Colors.blue),
)

Parameter Lists #

IntroductionScreen parameters #

Many parameters can be used to customize your app introduction like you want! This is the full list:

Pages

• Page that will be display (PageViewModel), by adding pages: [..] parameter.
• Use your own pages (Widget) without using those predefined, by adding rawPages: [..] parameter.
  • If you provide both rawPages and pages parameter, pages will be used.

Callbacks

• Set a custom callback when done button is pressed, by adding onDone: () {} parameter.
  • This param is required if you define done param, EXCEPT if you set showDoneButton: false
  • If you set overrideDone param, it will be ignored.
• Set a custom callback when skip button is pressed, by adding onSkip: () {} parameter.
  • By default, it will go to the last page
  • If you set overrideSkip param, it will be ignored.
• Add callback to listen page changes, by adding onChange: (page) {} parameter.

Use pre-made buttons

• Define pre-made Done button child (Widget), by adding done: Text('Done')
  • This param or overrideDone are required, EXCEPT if you set showDoneButton: false
  • By providing done, the parameter onDone is also required.
• Define pre-made Next button child (Widget), by adding next: Text('Next')
  • This param is required, EXCEPT if you set showNextButton: false
• Define pre-made Skip button child (Widget), by adding skip: Text('Skip')
  • This param is required if you set showSkipButton: true Define pre-made Back button child (Widget), by adding back: Text('Back')
  • This param is required if you set showBackButton: true

Use custom buttons

If you want to control pages, you can use key param. Search this repo's Issues for more detailed information.

• Define your custom Done button (Widget), by using overrideDone
  • This param or done are required, EXCEPT if you set showDoneButton: false
  • This parameter has priority over the done parameter.
• Define your custom Next button (Widget), by using overrideNext
  • This param or next are required, EXCEPT if you set showNextButton: false
  • This parameter has priority over the next parameter.
• Define your custom Skip button (Widget), by using overrideSkip
  • This param or skip are required if you set showSkipButton: true
  • This parameter has priority over the skip parameter.
• Define your custom Back button (Widget), by using overrideBack
  • This param or back are required if you set showBackButton: true
  • This parameter has priority over the skip parameter.

Manage display of pre-made or custom buttons

• Hide/show Skip button, by adding showSkipButton: false parameter.
  • Default false
• Hide/show Next button, by adding showNextButton: false parameter.
  • Default true
• Hide/show Done button, by adding showDoneButton: false parameter.
  • Default true
• Hide/show Back button, by adding showBackButton: false parameter.
  • Default false

Controls

• Display or not the progress dots, by adding isProgress: false parameter.
  • Default true
• Enable or disable dots progress tap, by adding isProgressTap: false parameter.
  • Default true

Page

• Freeze the scroll, by adding freeze: true parameter.
  • Default false
• Duration of scrolling animation, by adding animationDuration: 400 parameter.
  • Default 350
• Initial page, by adding initialPage: 2 parameter.
  • Default 0
• You can provide a ScrollController for each page by adding scrollControllers: [..] parameter.
  • If you have 5 pages, you can provide 5 differents ScrollController.
  • If you want to have only one ScrollController for page 1, you can provide: scrollControllers: [controller1]
  • If you want to have only one ScrollController for page 3, you can provide: scrollControllers: [null, null, controller1]
  • Will be ignored for page(s) if useScrollView is set to false in PageViewModel(s)

Pages style

• Global background color, by adding globalBackgroundColor: Colors.blue parameter.
  • Tips: use Colors.transparent to display an image as background (using Stack with IntroductionScreen inside for example)
• Customize dots (progression) by adding dotsDecorator: DotsDecorator(...)
  • You can customize dots size, shape, colors, spacing.
• Customize dots container by adding dotsContainerDecorator: BoxDecorator(...)
  • You can customize container that contain controls.
• Skip/Back button flex, by adding skipOrBackFlex: 1 parameter.
  • Set 0 to disable Expanded behaviour, default 1
• Dots indicator flex, by adding dotsFlex: 1 parameter.
  • Set 0 to disable Expanded behaviour, default 1
• Next/Done button flex, by adding nextFlex: 1 parameter.
  • Set 0 to disable Expanded behaviour, default 1
• Animation curve between pages, by adding curve: Curves.elasticIn parameter.
  • Default Curves.easeIn

Buttons style

• Change global style of buttons (for skip, next, done, back), by adding baseBtnStyle parameter.
• Change skip button style, by adding skipStyle: TextButton.styleFrom(alignment: Alignment.centerLeft) parameter.
• Change next button style, by adding nextStyle: TextButton.styleFrom(alignment: Alignment.centerRight) parameter.
• Change done button style, by adding doneStyle: TextButton.styleFrom(splashFactory: NoSplash.splashFactory) parameter.
• Change back button style, by adding backStyle: TextButton.styleFrom(primary: Colors.red) parameter.

Semantic

• Change skip button semantic label, by adding skipSemantic: 'Skip introduction' parameter.
• Change next button semantic label, by adding nextSemantic: 'Go to next page' parameter.
• Change done button semantic label, by adding doneSemantic: 'Exit introduction' parameter.
• Change back button semantic label, by adding backSemantic: 'Go to previous page' parameter.

Layout

• Enable or disable SafeArea on top, by adding isTopSafeArea: true parameter
  • Default false
• Enable or disable SafeArea on bottom, by adding isBottomSafeArea: true parameter.
  • Default false
• Customize controls position on screen, by adding controlsPosition: const Position(left: 0, right: 0, bottom: 100) parameter.
  • Default const Position(left: 0, right: 0, bottom: 0)
• Customize margin of controls's container, by adding controlsMargin: EdgeInsets.all(16.0) parameter.
  • Default EdgeInsets.zero
• Customize padding of controls's container, by adding controlsPadding: EdgeInsets.all(8.0) parameter.
  • Default EdgeInsets.all(16.0)
• Add global header (top), static and displayed above pages, by adding globalHeader: Image.asset(...) parameter.
• Add global footer below controls/dots, by adding globalFooter: ElevatedButton(...) parameter.
• Change axis of scroll by adding pagesAxis: Axis.vertical.
  • Default Axis.horizontal
• Change default scroll physics of PageView by adding scrollPhysics: ClampingScrollPhysics().
  • Default BouncingScrollPhysics()
• You can also enable right-to-left behavior by adding rtl: true.
  • Default false
• Change default implicit scrolling behavior by adding allowImplicitScrolling: true
  • Default false
  • Reference: PageView's allowImplicitScrolling parameter

PageViewModel parameters #

You can provide many parameters to customize each pages:

• title: "Title of the page" or titleWidget: Text("Custom widget for title")
• body: "Body of the page" or bodyWidget: Text("Custom widget for body")
• image: Image.asset(...) image of the page.
  • It's expecting a Widget, so if you want to pass a Video, Text, or anything else, you can.
• footer: ElevatedButton(...), display a widget below body
  • Like image param, it's expecting a Widget, you can pass what you want.
• decoration: PageDecoration(...), page decoration to customize page
  • See next section for all parameters you can pass
• reverse: true, reverse order of image and content (title/body). (Default: false)
• useScrollView: false, by default pages use a Scrollview to handle small screen or long body text. You can remove ScrollView by setting to false.

PageDecoration parameters #

• pageColor: Colors.white, background color of the page
  • You cannot use both pageColor and boxDecoration params
• titleTextStyle: TextStyle(...), TextStyle of the title
• bodyTextStyle: TextStyle(...), TextStyle of the body
• boxDecoration: BoxDecoration(...), BoxDecoration of page container
  • You cannot use both pageColor and boxDecoration params
• imageFlex: 2, flex ratio of the image
• bodyFlex: 3, flex ratio of the content (title/body)
• imagePadding: EdgeInsets.only(bottom: 12.0), padding of the image Widget. (Default EdgeInsets.only(bottom: 24.0))
• contentPadding: EdgeInsets.only(all: 24.0), padding of the content (title/body/footer) Widget. (Default EdgeInsets.all(16))
• titlePadding: EdgeInsets.only(bottom: 24.0), padding of the title text/Widget. (Default EdgeInsets.only(top: 16.0, bottom: 24.0))
• descriptionPadding: EdgeInsets.only(bottom: 24.0), padding of the body text/Widget. (Default EdgeInsets.zero)
• footerPadding: EdgeInsets.only(top: 24.0), padding of the footer text/Widget. (Default EdgeInsets.symmetric(vertical: 24.0))
• bodyAlignment: Align.center, content (title, body, footer) alignment. (Default Align.topCenter)
• imageAlignment: Align.center, image alignment. (Default Align.bottomCenter)
• fullScreen: true, Set image as fullscreen (background). (Default false)