Unofficial hikari multi-page embed handler
- Message per embed or persistent message
- Index select that can be turned on/off
- Select labels are generated based on embed's title
- Index button that can be turned on/off
- Ability to set the buttons to any emote, color or label
- Custom buttons
Join our Discord server!
- Try out example commands,
- Ask some questions,
- And give us feedback and suggestions!
- Make an issue to:
- say what feature you want to be added
- file a bug report
- Make a pull request and:
- describe what you added/removed
- why you added/removed it
- Make sure you use the issue/PR template!
pip install -U hikari-Paginator
- hikari (version 2.0.0.dev106)
These simple examples show how to easily create interactive, multiple page embeds that anyone can interact with that automatically deactivate after 60 seconds of inactivity:
import discord
from discord.ext import commands
from discord_slash import SlashCommand, SlashContext
from dinteractions_Paginator import Paginator
bot = commands.Bot(command_prefix="/")
slash = SlashCommand(bot, sync_commands=True)
@bot.event
async def on_ready():
print(f"Logged in as {bot.user}!")
@slash.slash(name="embeds")
async def embeds(ctx: SlashContext):
one = discord.Embed(title="1st Embed", description="General Kenobi!", color=discord.Color.red())
two = discord.Embed(title="2nd Embed", description="General Kenobi!", color=discord.Color.orange())
three = discord.Embed(title="3rd Embed", description="General Kenobi!", color=discord.Color.gold())
four = discord.Embed(title="4th Embed", description="General Kenobi!", color=discord.Color.green())
five = discord.Embed(title="5th Embed", description="General Kenobi!", color=discord.Color.blue())
pages = [one, two, three, four, five]
await Paginator(bot=bot, ctx=ctx, pages=pages, content=["1", "2", "3", "4", "5"], timeout=60).run()
bot.run("token")
import discord
from discord.ext import commands
from discord_slash import SlashCommand
from dinteractions_Paginator import Paginator
bot = commands.Bot(command_prefix="/")
slash = SlashCommand(bot)
@bot.event
async def on_ready():
print(f"Logged in as {bot.user}!")
@bot.command()
async def embeds(ctx):
one = discord.Embed(title="1st Embed", description="General Kenobi!", color=discord.Color.red())
two = discord.Embed(title="2nd Embed", description="General Kenobi!", color=discord.Color.orange())
three = discord.Embed(title="3rd Embed", description="General Kenobi!", color=discord.Color.gold())
four = discord.Embed(title="4th Embed", description="General Kenobi!", color=discord.Color.green())
five = discord.Embed(title="5th Embed", description="General Kenobi!", color=discord.Color.blue())
pages = [one, two, three, four, five]
await Paginator(bot=bot, ctx=ctx, pages=pages, content=["1", "2", "3", "4", "5"], timeout=60).run()
bot.run("token")
bot
-commands.Bot
: The bot variable,commands.Bot
is requiredctx
Union[SlashContext, commands.Context, ComponentContext, MenuContext, discord.channel.TextChannel, discord.User, discord.Member]
: The context of a command.
NOTE: if one of the latter 3 are used, there will always be aThis interaction failed
even though it was a success, due to no context to respond to
pages
-Optional[List[discord.Embed]]
: the list of embeds to be paginated, defaults toNone
and paginatescontent
instead
NOTE:content
must be a list for paginating withoutpages
!content
-Optional[Union[str, List[str]]]
: the content of the message to send, defaults toNone
editOnMessage
-Optional[discord.Message]
: paginate in the specified message, defaults toFalse
files
-Optional[Union[discord.File, List[discord.File]]]
: files to send, defaults toNone
hidden
-Optional[bool]
: if you want the paginator to be hidden, defaultFalse
authorOnly
-Optional[bool]
: if you want the paginator to work for the author only, default isFalse
onlyFor
-Optional[Union[discord.User, discord.Role, List[Union[discord.User, discord.Role]]]]
: components only for specified user(s) or role(s)dm
-Optional[bool]
: if you want the paginator to be DM'ed, defaultFalse
customButton
-Optional[List[Union[dict, Awaitable]]]
: a list of a create_button(...) and an awaitable function, defaultNone
customActionRow
-Optional[List[Union[dict, Awaitable]]]
: a list of an action row and an awaitable function, defaultNone
See how to use these args here!
timeout
-Optional[int]
: deactivates paginator after inactivity if enabled, defaults toNone
(meaning no timeout)disableAfterTimeout
-Optional[bool]
: disable components aftertimeout
, defaultTrue
deleteAfterTimeout
-Optional[bool]
: delete components aftertimeout
, defaultFalse
timeoutEmbed
-Optional[discord.Embed]
: edit to embed aftertimeout
, defaults toFalse
useEmoji
-Optional[bool]
: uses the emoji, default isTrue
useButtons
-Optional[bool]
: uses buttons, default isTrue
useSelect
-Optional[bool]
: uses a select, default isTrue
useIndexButton
-Optional[bool]
: uses the index button, default isFalse
and staysFalse
ifuseButtons
is alsoFalse
useLinkButton
-Optional[bool]
: uses the link buttonuseQuitButton
-Optional[bool]
: quit button to end the paginator, defaultFalse
useFirstLast
-Optional[bool]
: uses the first and last buttons, defaultTrue
useOverflow
-Optional[bool]
: uses the overflow action row if there are too many buttons, defaultTrue
useNotYours
-Optional[bool]
: sends an ephemeral (hidden) message if the paginator is not yours (see authorOnly or onlyFor), defaultTrue
notYoursMessage
-Optional[str]
: the message to send if the paginator is not yours (see authorOnly or onlyFor), default"this paginator is not for you!"
firstLabel
-Optional[str]
: The label of the button used to go to the first page, defaults to""
prevLabel
-Optional[str]
: The label of the button used to go to the previous page, defaults to""
indexLabel
-Optional[str]
: The label of the index button, defaults to"Page"
nextLabel
-Optional[str]
: The label of the button used to go to the next page, defaults to""
lastLabel
-Optional[str]
: The label of the button used to go to the last page, defaults to""
linkLabel
-Optional[Union[str, List[str]]]
: The label for the link buttonlinkURL
-Optional[Union[str, List[str]]]
: The URL(s) for the link buttonquitButtonLabel
-Optional[str]
: The label of the quit button, default"Quit"
firstEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the button used to go to the first page, defaults to"⏮️"
prevEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the button used to go to the previous page, defaults to"◀"
nextEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the button used to go to the next page, defaults to"▶"
lastEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the button used to go to the last page, defaults to"⏭️"
quitButtonEmoji
-Optional[Union[discord.emoji.Emoji, discord.partial_emoji.PartialEmoji, dict, str]
: emoji of the quit button, defaults toNone
firstStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the first button, defaults to1
(ButtonStyle.blue
)prevStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the previous button, defaults to1
(ButtonStyle.blue
)indexStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the index button, defaults to3
(ButtonStyle.green
)nextStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the next button, defaults to1
(ButtonStyle.blue
)lastStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the last button, defaults to1
(ButtonStyle.blue
)quitButtonStyle
-Optional[Union[ButtonStyle, int]]
: the style of button (ButtonStyle
orint
) for the quit button, defaults to4
(ButtonStyle.red
)
@slash.slash(name="custom-action-row")
async def _custom_action_row(ctx: SlashContext):
# Embeds:
pages = [
discord.Embed(title="1"),
discord.Embed(title="2"),
discord.Embed(title="3"),
discord.Embed(title="4"),
discord.Embed(title="5"),
]
# Custom button:
custom_button = create_button(style=3, label="A Green Button")
# Function:
async def custom_function(self, button_ctx): # Required arguments
await button_ctx.send("test", hidden=True)
await self.ctx.send("lol")
# Paginator:
await Paginator(
bot,
ctx,
pages,
timeout=60,
customButton=[
custom_button,
custom_function,
], # Note that custom_function is not called
).run()
The code above runs a normal paginator, with 1 extra action row at the bottom!
@slash.slash(name="custom-action-row")
async def _custom_action_row(ctx: SlashContext):
# Embeds:
pages = [
discord.Embed(title="1"),
discord.Embed(title="2"),
discord.Embed(title="3"),
discord.Embed(title="4"),
discord.Embed(title="5"),
]
# Action row:
buttons = [
create_button(style=3, label="A Green Button"),
]
custom_action_row = create_actionrow(*buttons)
# Function:
async def custom_function(self, button_ctx): # Required arguments
await button_ctx.send("test", hidden=True)
await self.ctx.send("lol")
# Paginator:
await Paginator(
bot,
ctx,
pages,
timeout=60,
customActionRow=[
custom_action_row,
custom_function,
], # Note that custom_function is not called
).run()
The code above runs a normal paginator, with 1 extra action row at the bottom!
FYI: You can also use customButton
and customActionRow
together!
Also, you can do self.stop = True
in the custom function to stop the paginator.
You can use the paginator method self.goToPage(page)
to go to the specific page number in the message.
The parameter page
is the page number, starting from 1.
You can access all the attributes of class Paginator with self
, such as the original command's
context (self.ctx
), the bot variable (self.bot
), and other things that you passed into it!
ctx
-Union[commands.Context, SlashContext]
: The original contextbuttonContext
-ComponentContext
: The context for the paginator's componentstimeTaken
-int
: How long in seconds that user(s) used the paginator before the timeoutlastContent
-str
: The last content that the paginator stopped at after timeoutlastEmbed
-discord.Embed
: The last embed that the paginator stopped at after timeoutsuccessfulUsers
-List[discord.User]
: Users that successfully used the paginator, the first user is the invokerfailedUsers
-List[discord.User]
: Users that failed to use the paginator
- Contributors of discord-interactions
- dpy-slash-button-paginator