<fluid-passport> tag draws it. This page covers where it shows and how you open it from your theme.
On a Site, the storefront draws and places the Passport for you. A Site opens it with fluid.auth.openPassport(). See Passport and sign-in.
Add the Passport
The member storefront SDK script that Fluid adds to your storefront also defines the Passport, so your theme adds only the tag. A storefront that still loads the older member storefront SDK script doesn’t define it, and the tag draws nothing there. Ask Fluid support to move your storefront to the current script. Put the tag once inlayouts/theme.liquid, just before </body>:
layouts/theme.liquid
- One tag per page. Only the first Passport on a page answers your buttons and scripts. A second one logs a console warning.
- It replaces the theme’s account menu. While a Passport is on the page, it hides every
{% member_account %}menu, so a member never sees two. A Passport withplacement="off"hides nothing. See Add an account menu. - Don’t load the script yourself. A second copy of the script doesn’t take over the first one’s Passport.
Choose where it shows
Theplacement attribute sets how the Passport shows:
Every attribute on this page also works with a
data- prefix, such as data-placement. When a tag has both, the prefixed one wins. An unknown value falls back to the default.
Float it in a corner
A floating Passport takes these attributes:
For example, to put a smaller button in the bottom-left corner, clear of a chat button on the right:
Let the member choose the spot
When your tag sets noposition, the Passport’s list ends with a Passport settings row. There the member puts the button at the bottom left, center or right of the screen. The browser remembers their choice. When the browser blocks storage, the choice lasts until they leave the page.
Set position to one of the four corners to keep the button where you put it. Your corner wins, and the member then sees no Passport settings row. An inline, none or off Passport has no row either. Only the member can choose the center. The Passport doesn’t read bottom_center or any other value it doesn’t know, so that tag counts as setting no position, and the member chooses.
Put it in your header
To draw the button in your own layout, setplacement="inline" and put the tag where the button goes:
size. Its panel, up to 360px wide, opens beside the button, on the side of the screen with more room. A guest sees the Sign in link where the button would be.
Open it only from your own buttons
To draw no Passport button at all, setplacement="none" and give your own account button a data-fluid-passport-open attribute:
- One second after the page loads, if no visible element has
data-fluid-passport-openand nothing has opened the Passport, it falls back tofloating: its own button in the corner, or Sign in for a guest. It stays floating for as long as it’s on the page. - Visible means drawn. An opener counts unless it’s off the page, hidden by CSS (
display: noneorvisibility: hidden), fully transparent, or has no size. The check doesn’t look at where it is, so an opener moved off screen, such as in a closed drawer, still counts, and no fallback shows. Keep at least one opener on screen. - Use the attribute, not a click handler. The check looks for
data-fluid-passport-open, so a button that callsfluid.passport.open()from its own click handler doesn’t stop the fallback. - Show the opener to guests too. A guest who clicks it is sent to sign in. If you hide it from guests, the fallback adds its own Sign in link next to yours.
Show the member’s Sites
The Passport lists the member’s Sites only when the tag has thesite-menu attribute:
sites room opens the list instead.
Turn it off
placement="off" also makes no request for the member’s session. Member prices and the rest of the member storefront SDK keep working, because off turns off only the menu.
How it stays in view
In a browser with popovers, the Passport places its panel inside the part of the screen the visitor can see, in every placement:- It keeps 16px from every edge of what shows: inside the page’s scrollbars, above a phone’s or tablet’s on-screen keyboard, and within a pinch zoom.
- It opens where there’s room. A panel that would get under 160px on its side opens on the other side when that side has more room.
- Its height fits the space left. The panel is never taller than the room it has, and its content scrolls inside. In a very short window it keeps 160px, or all of what shows when that’s less, so none of it goes off screen.
- It moves with the screen. The panel is placed again when the window resizes, including a rotation or a zoom, when the page scrolls, and when the keyboard opens or closes.
How it behaves on phones
On a phone, the panel is a bottom sheet in every placement. The sheet takes the full width along the bottom of the screen, over a dimmed page, clear of the home indicator. A phone here means a screen narrower than 640px, or a touch screen under 500px tall, such as a phone held sideways. With the keyboard up, the sheet stands on top of the keyboard and is never taller than what shows. The sheet covers the Passport’s button, so it has its own close button at the top. A tap on the dimmed page closes it too. You don’t need a separate phone layout for it: an inline button in your header opens the same sheet.Over your theme’s layers
The open panel, and the phone sheet with its dimmed page, are drawn in the browser’s top layer, as a popover, in every placement. Nothing your theme stacks covers or clips it: not a header’soverflow: hidden, a z-index, a transform, a filter or contain. You don’t need to raise anything to keep it on top.
- The button uses
z-index. A floating button sits atz-index: 2147483000. Set thez-indexattribute to put something of your own, such as a chat button, above or below it. - Older browsers keep the panel in the page. A browser without popovers draws the panel at the Passport’s
z-indexinstead. There, an ancestor of the tag that has its own stacking context, such as a positioned ancestor with az-index, holds the panel at that ancestor’s level. So does an ancestor with atransform,filter,backdrop-filter,will-change: transformorcontain: paint. Keep an inline tag out of such an ancestor if you support those browsers. - A modal
<dialog>blocks it. Your theme’s own modal dialog makes the rest of the page inert, the Passport included. Close the dialog before you open the Passport. - A click outside closes it. That click doesn’t also reach the link or button under it. Escape closes it too, and focus goes back to what opened it.
Open it from your theme
You can open the Passport from a button or link, from a script, or with an event. Each one can name the room to open on. With afloating or inline Passport, the panel always opens from the Passport’s own button. With placement="none", it opens beside the element that opened it.
Rooms
A room is one part of the member’s account, opened inside the panel:
Any other value opens the list.
From a button or link
A click on any element withdata-fluid-passport-open opens the Passport, or closes it when it’s open. The attribute’s value, if any, names the room:
href for a page without the Passport. On a page with one, the click opens the Passport instead of following the link.
- With
placement="none", a click on a different opener while the panel is open moves it beside that opener and to that opener’s room. A click on the opener it’s open for closes it. - With
floatingorinline, a click on a different opener moves a panel that an opener opened to that opener’s room, and the panel stays at the Passport’s button. A panel the member opened from the Passport’s own button closes on a click on any opener. - While the panel is open, every opener has
aria-expanded="true", and"false"once it closes. When it closes, focus goes back to the opener that opened it. - With
placement="none", if the opener that opened it leaves the page, the panel moves to the next visible opener, or closes when there’s none.
From a script
The script addsfluid.passport to the page, next to anything else already on window.fluid:
openandtoggletakeroom, a room from the table above, andanchor, the element focus returns to on close. Withplacement="none", the panel also opens besideanchor, unless it’s hidden.- Without an
anchor, aplacement="none"panel opens beside the first visibledata-fluid-passport-openelement, or from the cornerpositionnames when there’s none. togglecloses an open panel, whatever room or anchor it names.- For a guest,
openandtogglesend the visitor to sign in instead. - A call made before the Passport knows who’s signed in is carried out once it does. A
close, or a secondtoggle, made before then cancels it. isOpenis read-only, and so isfluid.passport. Don’t assign it.
Before the script loads
The member storefront SDK loads as a module script, after your theme’s own inline scripts have run. To callfluid.passport from a script that may run first, put this stub before it:
fluid.passport as usual. When the script loads, it replaces the stub and replays the queued calls in order, once a Passport is on the page.
With events
You can also dispatch an event onwindow, with the same room and anchor in detail:
fluid-passport:opened and fluid-passport:closed, which bubble to window, with the room in detail.room:
open() and toggle(), which take the same options, and an isOpen property. They work on any <fluid-passport>, not only the first one on the page. To close it, use fluid.passport.close() or the close event, which put focus back on what opened it.
From a Site or a Mist page
A Site runs in its own frame, so it can’t add the tag, callfluid.passport or use data-fluid-passport-open. It opens the Passport from a click with fluid.auth.openPassport(), and so does a Site you build in Mist. See Open the Passport from your own button.
What not to do
- Don’t load the script a second time, or pin another version of it. See Add the Passport.
- Don’t add a second
<fluid-passport>. Only the first answers your openers, scripts and events. - Don’t set
position="bottom_center". The member then chooses the spot. See Let the member choose the spot. - Don’t open a
placement="none"Passport from a click handler, and don’t hide its opener from guests. See Open it only from your own buttons. - Don’t assign
fluid.passport. Use the stub, which keeps an API that’s already there.
For agents
To put the Passport’s button in a theme’s header, and add a button elsewhere that opens it on orders:- The page has exactly one
<fluid-passport>and loads the member storefront SDK script once. - The theme doesn’t also show a
{% member_account %}menu where the Passport should be. - Signed in, a click opens the panel, and Escape closes it and puts focus back.
- Signed out, the visitor sees Sign in, and an opener sends them to sign in.
- At a phone width, under 640px, the panel opens as a bottom sheet with its own close button.
- In a short window, and on a phone with the keyboard up, all of the panel stays on screen and its content scrolls.
- With
placement="none", the theme’s opener is visible to guests and members, and no corner button shows up a second after load.
fluid.auth.openPassport() from a click instead, and check it on the published Site. See Passport and sign-in.